search

open-rpc / spec

The OpenRPC specification
https://spec.open-rpc.org
Apache License 2.0
167 stars 51 forks source link

Describe the advantages of open-rpc over openapi #112

Closed gracenoah closed 4 years ago

gracenoah commented 5 years ago

There's a perfectly good existing spec for describing JSON based or any other HTTP APIs, so what's the purpose of this project? Why have yet another standard with yet another set of tools to generate code? What's the difference between open-rpc and openapi? The FAQ doesn't answer these questions. The list of projects that use json-rpc includes a lot of projects that don't have an official openapi spec, which is unfortunate, but I don't see why creating a different standard solves this problem.

BelfordZ commented 5 years ago

Hey @gracenoah,

Thank you very much for your question. I'm putting together a thoughtful response and will be making a PR with @shanejonas soon.

BelfordZ commented 5 years ago

Q: There's a perfectly good existing spec for describing JSON based or any other HTTP APIs, so what's the purpose of this project?

This project is a fork of openapi. It was modified to accommodate JSON-RPC APIs. JSON-RPC has a few properties that don't fit within openapi.

  1. openapi is path based. JSON-RPC over http is universally implemented as a single path endpoint. openapi is a giant awkward mess of oneOf and a single rest endpoint to make this work.

  2. JSON-RPC is transport-agnostic. You may send JSON-RPC messages over any medium you desire. This means that clients and servers should be able to handle http(s), websockets, Unix IPC and more.

  3. openapi deals with multi content types. JSON-RPC is JSON payloads only.

Q: Why have yet another standard with yet another set of tools to generate code?

For the above mentioned reasons, using openapi with JSON-RPC results in generated artifacts that are pretty much useless. They don't accommodate well for these needs. Googling "json rpc openapi" shows many people running into this deficiency.

While you could get some things to work, using openapi on anything but path & http based api is fitting a round peg to a square hole.

Q: What's the difference between open-rpc and openapi?

I think this has been addressed above, but we should add a section that addresses this question specifically.

The spec has a sentence that we should use to answer this:

Not all services can be described by OpenRPC — this specification is not intended to cover REST APIs - It is exclusively for APIs which adhere to the JSON-RPC 2.0 spec.

The list of projects that use json-rpc includes a lot of projects that don't have an official openapi spec, which is unfortunate, but I don't see why creating a different standard solves this problem.

Hopefully you understand why they dont exist already. It's not that the users of JSON-RPC don't know about openapi. The issue is that all in all, openapi is just not well suited for JSON-RPC. While you could get some things to work, its fitting a round peg to a square hole.

@gracenoah Please let me know if you have any other questions, or if you feel there is a way to improve these answers. Thanks again for taking the time to ask, and helping us make it more clear why we are doing this.

BelfordZ commented 5 years ago

Im gonna leave this up for a little while to have some time to improve it. Later this week Ill make a PR adding it as FAQ.

@gracenoah if you are interested in helping out, I'd greatly appreciate the help if you could make this into a PR.

gracenoah commented 5 years ago

This all makes a lot of sense! What I was not understanding is that this spec covers only APIs that have a single "endpoint" and all messages are entirely encoded in json payloads. It seems like open-rpc could produce much better specs for the types of projects that have APIs that fit this model. I think the code generators will actually be much, much simpler than the openapi ones!

stale[bot] commented 4 years ago

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.