API Styles

Four different clients need the same information from BoxOffice — "which events are on sale, and how many seats are left?":

• the web app, rendering an event page that combines catalog data, the seat map and availability;
• the mobile app, on a congested 4G connection in a stadium queue, where every kilobyte and round trip counts;
• a reseller partner that integrates once and then expects the API never to break;
• the internal order service, which asks inventory to confirm holds thousands of times per second during on-sale.

One API style does not fit all four. This page compares the four families you will meet in practice — REST, gRPC, GraphQL and asynchronous APIs — on the same BoxOffice resource, and then covers what matters more than the style: designing the contract well and evolving it without breaking anyone.

An API is a contract

An API (Application Programming Interface) is the contract between a provider (the service that implements it) and its consumers (the code that calls it): which operations exist, what they accept and what they return — and nothing about how they are implemented. A stable contract is what lets the catalog team rewrite its persistence layer without telling anybody, and what lets the mobile team ship without waiting for the backend.

Three consequences shape everything below:

• Expose DTOs, not entities. A DTO (Data Transfer Object) is a class whose only job is to cross the boundary. Returning the JPA entity ties the contract to the database schema and leaks internal fields.
• The contract is a document, not just code. OpenAPI (REST), .proto files (gRPC), the GraphQL schema and AsyncAPI (events) describe it in a machine-readable way, from which clients, servers, mocks and tests are generated.
• Changing the contract is a negotiation. Anything a consumer can observe — a field name, a status code, the order of a list — is part of it.

One resource, four styles

The resource: an event with its availability (seats left per section). Here is how each style expresses "give me event evt_42 with its availability".

GET /v1/events/evt_42?include=availability HTTP/1.1
Accept: application/json

openapi: 3.1.0
info: { title: BoxOffice Catalog API, version: 1.4.0 }
paths:
  /v1/events/{eventId}:
    get:
      operationId: getEvent
      parameters:
        - { name: eventId, in: path, required: true, schema: { type: string } }
        - { name: include, in: query, schema: { type: string, enum: [availability] } }
      responses:
        "200":
          description: The event
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Event" }
        "404": { $ref: "#/components/responses/NotFound" }
components:
  schemas:
    Event:
      type: object
      required: [id, title, startsAt, venue]
      properties:
        id: { type: string, example: evt_42 }
        title: { type: string, example: "Stadium Tour — São Paulo" }
        startsAt: { type: string, format: date-time }
        venue: { $ref: "#/components/schemas/VenueRef" }
        availability:
          type: array
          items:
            type: object
            properties:
              section: { type: string, example: "PISTA" }
              seatsLeft: { type: integer, example: 1180 }
              priceCents: { type: integer, example: 45000 }

syntax = "proto3";
package boxoffice.inventory.v1;

import "google/protobuf/timestamp.proto";

service InventoryService {
  rpc GetAvailability (GetAvailabilityRequest) returns (Availability);
  // server streaming: the seat map pushes changes while the fan looks at it
  rpc WatchAvailability (GetAvailabilityRequest) returns (stream AvailabilityChange);
}

message GetAvailabilityRequest {
  string event_id = 1;
}

message Availability {
  string event_id = 1;
  repeated Section sections = 2;
  google.protobuf.Timestamp as_of = 3;
}

message Section {
  string name = 1;
  int32 seats_left = 2;
  int64 price_cents = 3;
}

message AvailabilityChange {
  string section = 1;
  int32 seats_left = 2;
}

type Query {
  event(id: ID!): Event
  events(city: String, first: Int = 20, after: String): EventConnection!
}

type Event {
  id: ID!
  title: String!
  startsAt: DateTime!
  venue: Venue!
  availability: [SectionAvailability!]!   # resolved by the inventory service
}

type SectionAvailability {
  section: String!
  seatsLeft: Int!
  priceCents: Int!
}

query EventCard {
  event(id: "evt_42") {
    title
    startsAt
    availability { section seatsLeft }
  }
}

asyncapi: 3.0.0
info: { title: BoxOffice Inventory Events, version: 1.0.0 }
channels:
  availabilityChanged:
    address: inventory.availability.v1
    messages:
      AvailabilityChanged:
        payload:
          type: object
          required: [eventId, section, seatsLeft, occurredAt]
          properties:
            eventId: { type: string, example: evt_42 }
            section: { type: string, example: PISTA }
            seatsLeft: { type: integer, example: 1179 }
            occurredAt: { type: string, format: date-time }
operations:
  publishAvailabilityChanged:
    action: send
    channel: { $ref: "#/channels/availabilityChanged" }

REST in practice

REST (Representational State Transfer) was defined by Roy Fielding as an architectural style on top of HTTP semantics¹². In practice "REST API" means Richardson maturity level 2: resources with their own URLs, correct HTTP methods and status codes³.

Resources and methods for BoxOffice

Safe means the request does not change server state (caches and crawlers may call it freely). Idempotent means doing it twice has the same effect as doing it once, so it is safe to retry. POST is neither — which is why every POST that creates money-related state in BoxOffice requires an idempotency key (integrations).

Status codes that carry meaning

Errors deserve a uniform body. RFC 9457 Problem Details for HTTP APIs defines one (application/problem+json) that Spring Boot (3 and later) supports out of the box via ProblemDetail⁴:

{
  "type": "/problems/seat-unavailable",
  "title": "Seat unavailable",
  "status": 409,
  "detail": "Seat C-14 is held by another fan.",
  "instance": "/v1/events/evt_42/holds",
  "unavailableSeats": ["C-14"]
}

Pagination: offset vs cursor

The cursor is an opaque string (often base64 of the last row's sort key) that the client sends back unchanged.

Caching and long-running operations

• Conditional requests: catalog returns ETag: "v17" and Cache-Control: public, max-age=30; a client that repeats the request with If-None-Match: "v17" gets 304 Not Modified with no body. The CDN (edge) does the same at scale — another reason to keep reads as cacheable GETs.
• Long-running operations: never hold a connection for 30 s. Answer 202 Accepted with a Location: /v1/orders/ord_9 status resource, and let the client poll it or receive a push. Checkout uses exactly this while the payment provider decides.

The contract in code

With springdoc-openapi, the OpenAPI document is generated from the annotated controller (code-first); alternatively the YAML is written first and the controller interface is generated from it (contract-first, e.g. with openapi-generator). Contract-first fits APIs consumed by partners; code-first is faster for internal ones.

@RestController
@RequestMapping("/v1/events")
@Tag(name = "Events")
class EventController {

    private final EventQueries queries;

    EventController(EventQueries queries) { this.queries = queries; }

    @GetMapping("/{eventId}")
    @Operation(summary = "Get one event, optionally with seat availability")
    ResponseEntity<EventDto> get(@PathVariable String eventId,
                                 @RequestParam(required = false) Include include) {
        EventDto event = queries.find(eventId, include == Include.AVAILABILITY)
                .orElseThrow(() -> new ErrorResponseException(HttpStatus.NOT_FOUND));
        return ResponseEntity.ok()
                .eTag(event.version())
                .cacheControl(CacheControl.maxAge(Duration.ofSeconds(30)).cachePublic())
                .body(event);
    }
}

Hands-on 1 builds a simpler version of this controller (box below).

@RestController
@RequestMapping("/catalog/events")
public class EventController {

    private final CatalogService service;

    public EventController(CatalogService service) {
        this.service = service;
    }

    @GetMapping
    public PageOut<EventOut> list(
            @RequestParam(required = false) String city,
            @RequestParam(defaultValue = "0") @Min(0) int page,
            @RequestParam(defaultValue = "20") @Min(1) @Max(50) int size) {
        return service.upcomingEvents(city, page, size);
    }

    @GetMapping("/{id}")
    public EventOut get(@PathVariable Long id) {
        return service.findEvent(id);
    }

    @PostMapping
    public ResponseEntity<EventOut> create(@Valid @RequestBody EventIn in) {
        var out = service.createEvent(in);
        return ResponseEntity.created(URI.create("/catalog/events/" + out.id())).body(out);
    }

gRPC in practice

gRPC is an RPC framework from Google built on HTTP/2 and Protocol Buffers⁵. What you get:

• Generated, typed clients in a dozen languages from one .proto — calling inventory.getAvailability(req) looks like a local method call.
• Compact binary messages and cheap parsing: protobuf payloads are typically several times smaller than the equivalent JSON, which matters for chatty internal traffic.
• Multiplexing: many concurrent calls over one HTTP/2 connection.
• Streaming: unary, server streaming (WatchAvailability above), client streaming and bidirectional.
• Deadlines that propagate: the caller says "I need an answer within 300 ms", and every hop knows how much time is left.

And what it costs:

• Browsers cannot call it directly: you need gRPC-Web or Connect through a proxy, or a REST/GraphQL facade at the edge.
• Load balancing is subtle: one long-lived HTTP/2 connection carries all calls, so an L4 load balancer pins all traffic of a client to one server. Use an L7 proxy (Envoy, a service mesh) or client-side load balancing (edge).
• Harder to debug by hand: binary on the wire; use grpcurl and server reflection.

Typical use: high-volume, internal, service-to-service calls — order → inventory during on-sale — where both sides are yours.

GraphQL in practice

GraphQL is a query language and runtime for APIs⁶. The client sends a query describing the shape of the data it wants; the server's resolvers fetch each field, possibly from different services.

• No over-fetching or under-fetching: one round trip returns exactly what a screen needs — attractive for mobile.
• A typed schema with introspection: great tooling and self-documentation.
• Evolution without versions: add fields freely, mark old ones @deprecated, remove them when usage drops to zero.

The problems to plan for:

• The N+1 problem: listing 20 events, each with availability, naively triggers 1 + 20 calls to inventory. Batch them with a DataLoader (collect the 20 ids, make one call).
• Caching is harder: queries usually go as POST to one URL, so HTTP caches and CDNs do not help by default. Persisted queries (the client sends a hash of a pre-registered query, possibly with GET) restore cacheability and block arbitrary queries.
• Abusive queries: a deeply nested query can be very expensive. Limit depth and compute a query cost budget per client.
• Authorization per field, not per endpoint.

Typical use: a BFF (Backend for Frontend) — one GraphQL layer per front-end that composes catalog, inventory and search for the screens. Large organizations use federation to let each team own part of one graph.

Asynchronous APIs

Not every interaction is a question that needs an immediate answer. Asynchronous styles remove the caller's wait:

The contract still matters: event schemas need the same discipline as REST payloads — documented (AsyncAPI), versioned and evolved compatibly (schema registry, messaging).

Choosing a style

flowchart TD
    q1{"Does the caller need<br/>the result to continue?"} -->|no| async["Async: event or queue<br/>(or a webhook to a partner)"]
    q1 -->|yes| q2{"Who is the consumer?"}
    q2 -->|"browser, partner,<br/>public"| q3{"Does one screen need data<br/>from many services?"}
    q3 -->|yes| gql["GraphQL BFF<br/>(REST underneath)"]
    q3 -->|no| rest["REST + OpenAPI"]
    q2 -->|"internal service,<br/>high volume or streaming"| grpc["gRPC"]
    q2 -->|"internal service,<br/>moderate volume"| rest

Real systems mix them. BoxOffice: REST at the public edge and for partners, a GraphQL BFF for the web and mobile apps, gRPC between order and inventory, events for everything that happens because an order was confirmed, and webhooks in from the payment provider.

Evolving a contract

APIs change. The first question for every change is whether it is breaking — whether an existing, unchanged consumer would stop working:

Compatible changes rely on consumers being tolerant readers: they ignore fields they do not know (Jackson does by default in Spring Boot — keep it so). Each style has its own rules:

• REST/JSON: tolerant readers + optional fields; breaking changes go to a new major version.
• Protobuf: never change or reuse a field tag; when you delete a field, mark its tag reserved so nobody reuses it; adding fields is always safe.
• GraphQL: no versions — add fields, deprecate with @deprecated(reason: …), remove when usage telemetry says nobody asks for them.
• Events: the schema registry checks compatibility on every new version; old events stay in the log forever, so consumers must read every version that was ever written.

When a breaking change is unavoidable, version and migrate:

Then expand and contract (parallel change): ship v2 next to v1, migrate consumers, watch v1 traffic fall to zero, announce the date with the Sunset header (RFC 8594)⁷, and only then remove v1.

How it connects

flowchart LR
    CON["API = contract<br/>OpenAPI, proto, schema"] --> REST["REST<br/>public, cacheable"]
    CON --> GRPC["gRPC<br/>internal, high volume"]
    CON --> GQL["GraphQL BFF<br/>one screen, many services"]
    CON --> ASYNC["async: events, queues,<br/>webhooks → Messaging"]
    REST --> HTTP["status codes, cursor pagination,<br/>Cache-Control → CDN"]
    REST --> IDEM["idempotency keys<br/>→ Integrations"]
    GRPC --> H2["HTTP/2, streaming, deadlines<br/>→ Edge protocols"]
    CON --> EVO["compatible evolution,<br/>contract tests"]
    EVO --> VER["breaking change: new version,<br/>expand and contract"]
    ASYNC --> SCH["event schemas evolve too<br/>→ Messaging semantics"]

Palette components: app (every service publishes a contract) · client · mobile (consumers of the REST API and the GraphQL BFF) · cdn (caches the cacheable GETs) · queue (commands) · kafka (events such as OrderConfirmed) · payment (calls BoxOffice back by webhook). Scenarios: event-fanout, payment-system, chat (server push). Continues in: Edge — protocols, Edge — API gateway, Messaging — schema evolution, Integrations — idempotency keys, Hands-on 1.

Key takeaways