API Design

OpenAPI is the de-facto standard for API documentation, code generation, mock servers, and contract testing. Most APIs you build should have an OpenAPI spec.

JSON Schema is the standard way to document and validate API request/response shapes. OpenAPI 3.1 fully adopts it. Know it if you design APIs.

GraphQL solves over-fetching and under-fetching in complex UIs. If your frontend needs flexible, composable data queries across multiple entity types, GraphQL is the tool.

gRPC is the dominant service-to-service RPC in polyglot microservices. Smaller payloads and faster than JSON/REST for high-throughput internal APIs.

Protobuf is the wire format for gRPC and many high-performance internal APIs. Schemas are also used for event/message contracts in Kafka/pubsub systems.

If you have event-driven systems (Kafka, RabbitMQ, WebSocket APIs, IoT), AsyncAPI is the description format. Analogous to OpenAPI for async what OpenAPI is for REST.