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

[shanejonas]

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.
  

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

• The art of naming variables
• Describe the advantages of open-rpc over openapi

[meowsbits]

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