This uses the architectural proposal format found here: https://github.com/CMSgov/easi-app/blob/master/docs/adr/index.md
Proposal to adopt the OpenRPC standard across KBase services and (eventually) apps.
OpenRPC defines a JSON-RPC 2.0 API along with JSON-Schema draft07 schemas for the parameter and result content.
There exists some JS tooling for OpenRPC, but not for Python. We would need a library similar to jsonrpcbase that is able to read an OpenRPC document to generate a set of validated methods while staying transport layer agnostic.
We would not have to replace all existing servers/apps with OpenRPC, but instead upgrade existing repos incrementally and use it for new apps.
- JSON-RPC 1.1 with KIDL (no change)
- gRPC
- OpenAPI
TBD
+JSON-RPC and JSON-Schema are already used across KBase, making adoption easier.+The JSON-RPC and OpenRPC specs are small and easy to understand+JSON-Schema has robust validation features and cross-language libraries+From the client perspective, requests and responses are the same as JSON-RPC 2.0+Transport layer agnostic, and could potentially be RESTful+Automatic validation of parameters and results using JSON Schema+Automatic documentation of APIs by converting OpenRPC JSON to html or markdown-We need to implement some OpenRPC base libraries in Python-OpenRPC is not super popular and has limited tooling-KBase mostly uses JSON-RPC 1.1, and OpenRPC only uses 2.0-In HTTP requests, JSON-RPC does not make use of path, query params, or headers-A little harder to ad-hoc curl, as you have to write out a json body and can't use paths
+No work required, everything can remain the same-No type validation in python (about the same benefit as documenation)-KIDL is not a community standard and is a custom language-JSON-RPC 1.1 is a draft version, not official, and is now out of date-KIDL is missing validation features such as regexes-Cannot expand or maintain the KIDL parser
+Robust, cross-language tooling, many features+Large community-Radically different from current setup; no overlap except for the idea of RPC-Protobufs are not human readable and you can't make simple curl requests-API is designed using a domain specific language rather than a generic format like JSON or YAML-No performance benefit in using Protobufs for KBase
+Very popular, lots of cross-language tooling, large community+Many features-Very complex-Radically different from current setup-Not transport agnostic, only HTTP, so would not work well with apps-Apps are oriented around method calls, not resources
JSON-RPC 2.0 with KIDL should also be considered, potentially as a stepping stone to OpenRPC.