API Design

https://graphql.org/
https://graphql-java.readthedocs.io/en/latest/index.html
https://github.com/graphql-java/graphql-java-http-example/blob/master/src/main/java/com/graphql/example/http/HttpMain.java


https://www.howtographql.com/graphql-java/0-introduction/

https://puncsky.com/hacking-the-software-engineer-interview#data-stores-todo

Public API Choices: JSON RPC vs. GraphQL vs. REST vs. gRPC 

Public API Choices

In summary, to choose a tool for the public API, API gateway, or BFF (Backend For Frontend) gateway, I prefer GraphQL for its features like tailing results, batching nested queries, performance tracing, and explicit caching.

	JSON RPC	GraphQL	REST	gRPC
Usecases	Etherum	Github V2, Airbnb, Facebook BFF / API Gateway	Swagger	High performance, Google, internal endpoints
Single Endpoint	✅	✅	❌	✅
Type System	✅ as weak as JSON  No uint64	✅  No uint64	✅ w/ Swagger  No uint64	✅  has uint64
Tailored Results	❌	✅	❌	❌
Batch nested queries	❌	✅	❌	❌
Versioning	❌	Schema Extension	Yes, w/ v1/v2 route s	Field Numbers in protobuf
Error Handling	Structured	Structured	HTTP Status Code	Structured
Cross-platform	✅	✅	✅	✅
Playground UI	❌	GraphQL Bin	Swagger	❌
Performance tracing	?	Apollo plugin	?	?
caching	No or HTTP cache control	Apollo plugin	HTTP cache control	Native support not yet. but still yes w/ HTTP cache control
Problem	Lack of community support and toolchainBarrister IDL	42.51 kb client-side bundle size	Unstructured with multiple endpoints. awful portability.	Grpc-web dev in progress140kb JS bundleNot all places support HTTP2

https://githubengineering.com/the-github-graphql-api/

GraphQL is a querying language developed by Facebook over the course of several years. In essence, you construct your request by defining the resources you want. You send this via a POST to a server, and the response matches the format of your request.

There are several other features of GraphQL that we hope to make available to clients, such as:

• The ability to batch requests, where you can define dependencies between two separate queries and fetch data efficiently.
• The ability to create subscriptions, where your client can receive new data when it becomes available.
• The ability to defer data, where you choose to mark a part of your response as time-insensitive.

REST, RPC, GraphQL, WebHooks, and WebSockets are some of the most popular standards today

Update
Use PUT for replacing a resource and PATCH for partial updates for existing resources.

Create
Use POST for creating new resources.

codes in the 4XX range indicate a client-side error (like a missing required parameter or too many requests). Codes in the 5XX range indicate server-side errors.

SHOWING RELATIONSHIPS
A resource that exists only within another resource can be better represented as a subresource instead of a top-level resource in the URL. This makes the relationship clear for the developers using the API.

For instance, the GitHub API uses subresources to represent relationships in various APIs:

POST /repos/:owner/:repo/issues
Create an issue.
GET /repos/:owner/:repo/issues/:number
Retrieve an issue.
GET /repos/:owner/:repo/issues
List all issues.
PATCH /repos/:owner/:repo/issues/:number
Edit an issue.

NON-CRUD OPERATIONS

Render an action as part of a field of a resource. 

Treat an action like a subresource. The GitHub API uses this pattern for locking and unlocking an issue. PUT /repos/:owner/:repo/issues/:number/lock locks an issue.

Some operations, such as search, are even more difficult to fit in the REST paradigm. A typical practice in that case is to use just the action verb in the API URL. GET /search/code?q=:query: finds files in GitHub matching the given query.

RPC

a client executes a block of code on another server. Whereas REST is about resources, RPC is about actions. Clients typically pass a method name and arguments to a server and receive back JSON or XML.

The endpoints contain the name of the operation to be executed.

API calls are made with the HTTP verb that is most appropriate: GET for read-only requests and POST for others.

RPC style works great for APIs that expose a variety of actions that might have more nuances and complications than can be encapsulated with CRUD or for which there are side effects unrelated to the “resource” at hand. RPC-style APIs also accommodate complicated resource models or actions upon multiple types of resources.

GET /users.get?id=<id>

GraphQL allows clients to define the structure of the data required, and the server returns exactly that structure

a WebHook is simply a URL where API providers send a POST request when something happens

Designing for Real-Life Use Cases

Work Toward Consistency

You want your API to be intuitively consistent. That should be reflected in your endpoint names, input parameters, and output responses. Developers should be able to guess parts of your API even without reading the documentation. Unless you are making a significant version bump or large release, it’s best to work toward consistency when designing new aspects of an existing API.

Make Troubleshooting Easy

returning meaningful errors as well as by building tooling.

Logging on HTTP statuses, errors and their frequencies, and other request metadata is valuable to have, for both internal and external use

Building a versioning system is easier if it’s baked into the design at an early stage