Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Describe the advantages of open-rpc over openapi #112

Closed
gracenoah opened this issue Mar 20, 2019 · 4 comments

Comments

@gracenoah
Copy link

commented Mar 20, 2019

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

This comment has been minimized.

Copy link
Member

commented Mar 20, 2019

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 BelfordZ self-assigned this Mar 20, 2019

@BelfordZ BelfordZ added this to To do in OpenRPC via automation Mar 20, 2019

@BelfordZ

This comment has been minimized.

Copy link
Member

commented Mar 20, 2019

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

This comment has been minimized.

Copy link
Member

commented Mar 20, 2019

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

This comment has been minimized.

Copy link
Author

commented Mar 20, 2019

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!

@shanejonas shanejonas pinned this issue Mar 22, 2019

@BelfordZ BelfordZ added this to the 1.0.0 milestone Mar 26, 2019

@BelfordZ BelfordZ removed this from the 1.0.0 milestone Apr 1, 2019

@BelfordZ BelfordZ closed this Apr 1, 2019

OpenRPC automation moved this from To do to Done Apr 1, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
3 participants
You can’t perform that action at this time.