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 · 6 comments
Closed

Describe the advantages of open-rpc over openapi #112

gracenoah opened this issue Mar 20, 2019 · 6 comments
Assignees
Projects

Comments

@gracenoah
Copy link

@gracenoah gracenoah 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
Copy link
Member

@BelfordZ BelfordZ 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
Copy link
Member

@BelfordZ BelfordZ 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
Copy link
Member

@BelfordZ BelfordZ 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
Copy link
Author

@gracenoah gracenoah 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
@BelfordZ BelfordZ unpinned this issue Dec 20, 2019
@openrpc-bastion openrpc-bastion pinned this issue Apr 30, 2020
OpenRPC automation moved this from Done to In progress Apr 30, 2020
@BelfordZ
Copy link
Member

@BelfordZ BelfordZ commented Apr 30, 2020

@gracenoah would you be interested in helping out by maintaining the FAQ?

@stale
Copy link

@stale stale bot commented Jun 30, 2020

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.

@stale stale bot added the stale label Jun 30, 2020
@stale stale bot closed this Jul 8, 2020
OpenRPC automation moved this from In progress to Done Jul 8, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
OpenRPC
  
Done
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants