https://github.com/mastercloudapps-projects/rest-grpc-graphql
This project aims to provide a high level analysis and comparison between several API styles
https://github.com/mastercloudapps-projects/rest-grpc-graphql
api graphql hateoas openapi rest restful
Last synced: 3 months ago
JSON representation
This project aims to provide a high level analysis and comparison between several API styles
- Host: GitHub
- URL: https://github.com/mastercloudapps-projects/rest-grpc-graphql
- Owner: MasterCloudApps-Projects
- License: apache-2.0
- Created: 2020-06-30T09:35:05.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2020-12-12T21:58:06.000Z (over 4 years ago)
- Last Synced: 2025-03-24T11:45:56.184Z (3 months ago)
- Topics: api, graphql, hateoas, openapi, rest, restful
- Language: JavaScript
- Homepage:
- Size: 358 KB
- Stars: 24
- Watchers: 2
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# REST, gRPC and GraphQL
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.
## Demo project
See [implementation project](src/)
## Project description
1. [Introduction](docs/apis_introduction.md)
2. [REST](docs/rest.md)
3. [GraphQL](docs/graphql.md)
4. [gRPC](docs/grpc.md)
### Comparison table
| 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 |
## Additional resources
This project was born as a Master's Dissertation. You can check:
* 📖 [Essay (Spanish)](https://docs.google.com/document/d/1ldtcUz1kc_hQfbPyKY89YCCbSBH3ixZyTRLi_dX0DjA/edit)
* 🖼 [Slides (Spanish)](https://docs.google.com/presentation/d/1EMAOWbFpjjY3Zs9sdgdGa_lTynidE-upeEsLGu1KMDk/edit#slide=id.gb057fc3acf_0_45)
[Contract]: docs/usage/contract.md
[Schema definition]: docs/usage/schema_definition.md
[Standard methods]: docs/usage/methods.md
[Get]: docs/usage/method_get.md
[Get (representation)]: docs/usage/method_get#representation.md
[Get (custom)]: docs/usage/method_get#custom-fetching.md
[List]: docs/usage/method_list.md
[Create]: docs/usage/method_create.md
[Update]: docs/usage/method_update.md
[Partial update]: docs/usage/method_update_partial.md
[Delete]: docs/usage/method_delete.md
[Custom methods]: docs/usage/method_custom.md
[Long-requests]: docs/usage/long_running_operation.md
[Error handling]: docs/usage/error_handling.md
[Security]: docs/usage/security.md
[Subscriptions]: docs/usage/subscriptions.md
[Caching]: docs/usage/caching.md
[Discoverability]: docs/usage/discoverability.md