3 ms·

JsonRPC is also portable. Whole spec fits single page.

verdverm 3y ago
the JsonRPC comes from the typescript in GP, so the process of schema generation from types is not portable to other languages...
- mirekrusin 3y ago
  Typescript is mentioned as an example of function signature format. As it needs to describe only valid json values, the whole language needs to operate on 6 underlying data types only - it's really not that complicated to come up with minimal readable format that's easy to parse. It doesn't matter much if it reassembles ts, flow, ocaml or haskell - the point is it can fit into single screen, serve as documentation and be parseable for verification/codegen etc.
  - verdverm 3y ago
    Let's step back, and remember you posed JsonRPC as an alternative to OpenAPI or something like that? There is a whole lot more to express than... > 6 underlying data types only ... when automating REST documentation from some underlying source of truth It seems this one-page spec is woefully insufficient to express the concepts that OpenAPI can. Hence why no one here thinks this is a viable alternative
    - mirekrusin 3y ago
      OpenAPI is cluttered with protocol specifics that are irrelevant to something that is native to your host language (function signatures). Think of it as header file for api that is highly constrained (functions, notifications and json data types only - no classes, instances, polymorphism, no way to encode callbacks or returning functions etc. just basic algebra on json types - type aliases and unions). Imagine api like this: // @endpoint wss://localhost:3000/api/v1 notification heartbeat = { timestamp: number } type User = { id: string, email: Email type: "normal" | "admin" } type AuthError = { message: string, code: -123 } type NotLoggedInError = { message: string, code: -124 } // Logs you in. // // @throws AuthError login(username: string, password): User // Adds two numbers. // @throws NotLoggedInError add(x: number, y: number): number // Logs you out. // @throws NotLoggedInError logout(): null It's terse, straight forward and maps to your host programming language naturally.

the JsonRPC comes from the typescript in GP, so the process of schema generation from types is not portable to other languages...

mirekrusin 3y ago
Typescript is mentioned as an example of function signature format. As it needs to describe only valid json values, the whole language needs to operate on 6 underlying data types only - it's really not that complicated to come up with minimal readable format that's easy to parse. It doesn't matter much if it reassembles ts, flow, ocaml or haskell - the point is it can fit into single screen, serve as documentation and be parseable for verification/codegen etc.
- verdverm 3y ago
  Let's step back, and remember you posed JsonRPC as an alternative to OpenAPI or something like that? There is a whole lot more to express than... > 6 underlying data types only ... when automating REST documentation from some underlying source of truth It seems this one-page spec is woefully insufficient to express the concepts that OpenAPI can. Hence why no one here thinks this is a viable alternative
  - mirekrusin 3y ago
    OpenAPI is cluttered with protocol specifics that are irrelevant to something that is native to your host language (function signatures). Think of it as header file for api that is highly constrained (functions, notifications and json data types only - no classes, instances, polymorphism, no way to encode callbacks or returning functions etc. just basic algebra on json types - type aliases and unions). Imagine api like this: // @endpoint wss://localhost:3000/api/v1 notification heartbeat = { timestamp: number } type User = { id: string, email: Email type: "normal" | "admin" } type AuthError = { message: string, code: -123 } type NotLoggedInError = { message: string, code: -124 } // Logs you in. // // @throws AuthError login(username: string, password): User // Adds two numbers. // @throws NotLoggedInError add(x: number, y: number): number // Logs you out. // @throws NotLoggedInError logout(): null It's terse, straight forward and maps to your host programming language naturally.