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

REST over HTTP is over. Long Live REST over JSON-RPC. #30

Open
shanejonas opened this issue Jun 9, 2019 · 1 comment
Open

REST over HTTP is over. Long Live REST over JSON-RPC. #30

shanejonas opened this issue Jun 9, 2019 · 1 comment
Labels

Comments

@shanejonas
Copy link
Member

@shanejonas shanejonas commented Jun 9, 2019

This is the start of an article we might want to put on open-rpc.org, or somewhere, just putting it here to reference, possibly PR soon.

REST over HTTP is over. Long Live REST.

What is REST?

REST is a set of architectural guidelines for building APIs. It prescribes having resources as the interface for APIs and contains links pointing to relative resources to fetch additional information.

REST tied to HTTP is good, until its not

REST offers an ambiguous approach for API design, it's not a contract, not a specification, and not a reproducible process. It does contain HATEOS for specifying related resources, but only available at runtime.

Tight Coupling

REST over HTTP leaks protocol details (headers + url + body + status code + success/failure) into the application layer. This tight coupling limits its usefulness in modern production systems that want to provide an API with a wide array of transports like HTTP, HTTP2, Websocket, IPC, MQTT, etc.

Batching

There is no batching support for REST HTTP APIs out of the box. This leads to things like denormalizing the data and leaking it into other resources to cut down on expensive HTTP calls.

CRUD, then what?

Starting with CRUD(Create Read Update Destroy) and tying those to methods (GET PUT POST DELETE) lays out a simple design approach but adding complexity can end up in creating one-off, non-intuitive resources that only loosely relate to another.

HTTP Status Codes

Not only do status codes leak into the application layer, but they are relied on for errors. Application level errors map to 4xx error codes, except when they don't, like with a 404.

Failed x? 400 Bad Request.

Failed y? 418 I'm a teapot.

Can't find a resource? 404 Not found.

Success codes are also inconsistent; the status code for creating with POST is 201, unless it will return content, then the status code is 200.

No Standards

OpenAPI/swagger exists to provide documentation and interface definition, but it famously does not follow REST, furthering the move away from REST API design.

Path to API Enlightenment - REST over JSON-RPC

Based on Richardson Maturity Model description of the different layers of REST APIs. But applied with OpenRPC in mind:

  • Level 0 - Basic transport agnostic JSON-RPC API

  • Level 1 - Break down complexity into multiple resources or services.

  • Level 2 - Use a standard set of verbs and nouns removing unnecessary variation.

  • Level 3 - Introduce service discovery and links via the OpenRPC interface definition, providing a documentation-driven protocol.
    image

Transport agnosticism + REST Principles + Specification Driven Development

This is it! A self-documenting protocol, a contract driven API, with predictable names and simple protocol that can be used anywhere.

Alternatives

gRPC

gRPC is an RPC framework on protobufs. They have great naming conventions using imperative mood and NounVerb. But browser support is lacking.

Swagger/OpenAPI
Kafka

If you can avoid the request/response cycle you can use messaging systems like kafka.

More Resources

@shanejonas shanejonas changed the title REST over HTTP is over. Long Live REST. REST over HTTP is over. Long Live REST over JSON-RPC. Aug 23, 2019
@meowsbits
Copy link

@meowsbits meowsbits commented Mar 10, 2020

Over.. long... long... its over.. over long live.. it's over... REST... REST is life... wait, what?

Loading

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
2 participants