This project is an attempt to gather the foundations of three common API Styles –REST, gRPC and GraphQL. It also works as a guide on how each one of these styles tackles some everyday usage cases.
| Usage | REST | GraphQL | gRPC |
|---|---|---|---|
| Contract | HATEOAS or OpenAPI | GraphQL Schema Language: operations | Protocol Buffers: rpc |
| Schema definition | Resource oriented. HTTP response headers, Media Type and JSON Schema |
Graph oriented. GraphQL Schema Language |
Resource and Action oriented. Protocol Buffers: messages |
| Standard methods | GET, POST, PUT, PATCH, DELETE |
query and mutation |
Through rpc operations |
| Get | GET |
query |
Get rpc operation |
| Get (representation) | ✔️ Content Negotiation | ✘ Only JSON | ✘ only one. Default: Protocol Buffers |
| Get (custom) | Sparse fieldsets. Embedded resources | Native support | FieldMask |
| List | GET. Custom pagination, sorting and filtering |
query. Standard pagination and sorting |
List and Search rpc operations |
| Create | POST or PUT |
mutation |
Create rpc operation |
| Update | PUT |
mutation |
Update rpc operation (unrecommended) |
| Partial update | PATCH |
✘ Workarounds | Update rpc operation with FieldMask |
| Delete | DELETE |
mutation |
Delete rpc operation |
| Custom methods | HATEOAS or POST |
pure functions: query, other: mutation |
Custom rpc operation |
| Long-requests | Resource operation |
Interface Operation |
|
| Error handling | Native in HTTP. Extensible | errors property. Extensible |
Standard errors. Google Error Model |
| Security | HTTP: Bearer, OAuth, CORS, API Keys | HTTP: Bearer, OAuth, CORS, API Keys | TLS, ALTS, token-based (Google), custom |
| Subscriptions | Unsupported. WebHook and HTTP streaming | subscription |
HTTP/2 streaming |
| Caching | HTTP, application and local cache | GET, application and local cache |
Application and local cache |
| Discoverability | HATEOAS and OPTIONS or OpenAPI |
Native introspection | ✘ autogenerated client code |
This project was born as a Master's Dissertation. You can check: