Eight API communication patterns

• Client

  A program that asks another system for information or an action.

  Example: A shopping app requests a list of products from a service.

• API service

  A system that accepts structured requests from other software and returns results.

  Example: A weather service returns the forecast requested by an app.

• Event source

  Something that produces a notification when a change occurs.

  Example: A new order causes an order-created event.

REST

A resource-oriented interaction; this example retrieves one representation.

1. Client API service: GET /orders/42. The client identifies a resource using its URL.
2. API service Client: 200 + JSON. The service returns a representation.

GraphQL

A query selects fields, but efficient backend fetching still needs implementation.

1. Client API service: query { name }. The client submits a schema-checked field selection.
2. API service Client: { name }. The response follows the requested selection, with errors where appropriate.

gRPC

This native gRPC example streams typed messages; browser support differs.

1. Client API service: RPC request. A typed method call starts the stream.
2. API service Client: Message 1. The service emits one message.
3. API service Client: Message 2. Another ordered message arrives on this stream.
4. API service Client: Status OK. The call ends with a status.

SOAP

XML messages carry an envelope; contracts and validation depend on the service.

1. Client API service: XML envelope. The client sends the operation in a SOAP envelope.
2. API service Client: SOAP response. The service returns an envelope or a SOAP Fault.

WebSocket

After establishment, both endpoints can send independently.

1. Client API service: Connect. Establish a WebSocket connection.
2. API service Client: Event A. The server sends without a new request.
3. Client API service: Message B. The client sends on the same connection.
4. API service Client: Event C. Further server messages use that connection.

Webhook

The provider calls a registered recipient; verify signatures and handle retries.

1. Event source API service: Event. A provider-side event triggers delivery.
2. API service Client: POST event. The provider calls the recipient’s endpoint.
3. Client API service: 2xx ACK. The recipient acknowledges after its acceptance policy.

Server-sent events

One HTTP response carries a stream from server to browser.

1. Client API service: GET event stream. The browser opens the event stream.
2. API service Client: data: event 1. A server event arrives on the open response.
3. API service Client: data: event 2. Another event arrives; this channel is one-way.

Long polling

The server holds a request until data or a timeout, then the client opens another.

1. Client API service: GET updates. A request waits for new information.
2. Event source API service: New data. An event makes a response available.
3. API service Client: 200 + event. The response completes the request.
4. Client API service: Next GET. The client opens a new waiting request.