APIs Explained: REST, GraphQL and Good Design

Every app that shows a map, takes a payment or sends a message is calling an API. The interface hides implementation details, so the provider can change internals without breaking every client.

Good APIs are predictable. Names, error formats and pagination behave the same way everywhere, and a developer can guess the right call after reading one example.

REST, GraphQL and gRPC

REST models resources with HTTP verbs and URLs. It is simple, cacheable and universally understood, which is why it dominates public APIs. GraphQL exposes a typed schema and lets the client ask for exactly the fields it needs, which suits complex frontends with varied data requirements.

gRPC uses binary messages over HTTP/2 for fast, strongly typed service-to-service calls. It is common inside microservice architectures where performance and schema enforcement matter more than browser compatibility.

• REST: resource-oriented, cache-friendly, easy to debug.
• GraphQL: client-selected fields, one endpoint, strong typing.
• gRPC: compact binary transport, streaming, internal services.
• Webhooks: the provider calls you when something changes.

Authentication and authorisation

Public APIs use keys to identify a project, OAuth for delegated access on a user's behalf, and short-lived tokens for sensitive operations. Keys must be treated as secrets and rotated when exposed.

Authorisation is separate from authentication. A valid token still needs a permission check on every action, and object-level checks must prevent one customer from reading another's data by changing an identifier.

Design rules worth following

Return consistent shapes, use clear status codes, and paginate everything that could grow. Rate-limit with informative headers, document errors with stable codes, and make idempotency explicit so a retried payment does not charge twice.

Version deliberately. Additive changes are usually safe, but removing or renaming a field breaks clients that you cannot see. Deprecation notices with a migration window are cheaper than an outage.

• Use plural, predictable resource names.
• Return errors with a stable code and a human-readable message.
• Support pagination and filtering on every list endpoint.
• Provide an idempotency key for unsafe retries.
• Publish an OpenAPI or schema document and keep it current.
• Log requests with correlation IDs for support and debugging.

Using someone else's API

Read the rate limits and error codes before writing code, and implement retries with exponential backoff plus jitter. Cache responses where the provider allows it, and design so that an unavailable third party degrades gracefully instead of taking your product down.

Check the provider's deprecation policy and status history. A service that changes behaviour without notice is a liability no matter how good the documentation looks.

Key facts at a glance

Frequently asked questions