طراحی API: REST، OpenAPI و نسخه‌بندیAPI Design: REST, OpenAPI & Versioning

Let me open with an uncomfortable truth: writing code that "works" is easy; designing an API that lives for years, that thousands of consumers depend on, and that you can keep changing without breaking anyone — that is hard, and it is exactly where real senior skill shows. In this chapter you won't just learn how to write a @RestController; you'll understand why we make each design decision, which standards are genuinely current today, and how to talk about the "contract" between server and client in a senior interview.

Part 0 — a few words you must feel before we start

Before any code, four terms recur throughout this chapter. Let me plant them with analogies now.

• Resource: any addressable "thing" in your system — a user, an order, a product. A resource is a concept, not raw data.
• Representation: the shape a resource takes at a moment in time — say, that user as a JSON document. The resource "user 7" is one thing, but its representation can be JSON or XML.
• Idempotent: an operation whose final effect on the server is the same whether you do it once or a hundred times. Turning off a light is idempotent; pressing "off" 100 times still yields off. But "order a coffee" is not idempotent: a hundred times means a hundred coffees.
• Contract: the precise agreement about which request yields which response. This whole chapter is about keeping that contract solid and durable.

Mental model: REST is a style, not a protocol

REST stands for Representational State Transfer. The key point most people miss: REST does not tell you to use JSON, or even HTTP. REST is an abstract style. But in practice it's nearly always implemented over HTTP, because HTTP itself already embodies most of the same constraints. The most important ones are:

• Client–server: responsibilities are split; the UI evolves independently of data storage.
• Statelessness: each request must carry everything needed to understand it. The server "remembers" nothing about the client between requests.
• Cacheability: responses must declare whether and for how long they can be cached.
• Uniform interface: the heart of REST — resources are identified by URIs and manipulated through a standard set of verbs.

REST maturity: the Richardson model

Much of what people call a "REST API" is really half-REST. Leonard Richardson built a four-level model to describe how fully an API actually uses the web's capabilities. It's the famous Richardson Maturity Model (RMM).

Resources, verbs, and status codes

Name resources with nouns, not verbs

The correct pattern models resources as collections and members:

GET    /users          ← list users (a collection)
POST   /users          ← create a new user
GET    /users/7        ← read user 7
PUT    /users/7        ← full replacement of user 7
PATCH  /users/7        ← partial change to user 7
DELETE /users/7        ← delete user 7
GET    /users/7/orders ← orders of user 7 (nested resource)

HTTP verbs and their two vital properties

Every HTTP verb has two properties that everything revolves around: safe means it doesn't change data, and idempotent means repeating it doesn't change the final effect.

This distinction comes straight from RFC 9110 (the HTTP Semantics reference, published in 2022, obsoleting RFC 7231).

Choose status codes correctly

The status code is the first thing a client reads. Misusing it — returning everything as 200 and hiding the error message in the body — is one of the most common anti-patterns.

Idempotency: saving the API from retry storms

Here's the problem: POST is inherently not idempotent. If the network between client and server drops, the client doesn't know whether the server received the request, so it retries. The industry-standard solution (popularized by Stripe, and now being standardized as the IETF draft draft-ietf-httpapi-idempotency-key-header, version 07 as of October 2025) is this: the client sends a unique key (usually a UUID) in an Idempotency-Key header. The server stores this key, and if the same key arrives again, instead of doing the work again it replays the previous response.

@RestController
@RequestMapping("/payments")
public class PaymentController {

    private final PaymentService paymentService;
    private final IdempotencyStore store; // e.g. backed by Redis

    public PaymentController(PaymentService s, IdempotencyStore store) {
        this.paymentService = s;
        this.store = store;
    }

    @PostMapping
    public ResponseEntity<PaymentResult> pay(
            @RequestHeader("Idempotency-Key") String key,
            @RequestBody PaymentRequest req) {

        // If we've seen this key before, replay the same result
        var cached = store.find(key);
        if (cached.isPresent()) {
            return ResponseEntity.ok(cached.get());
        }

        // Otherwise do the work and store the result under this key
        PaymentResult result = paymentService.charge(req);
        store.save(key, result); // must be atomic to avoid a race condition
        return ResponseEntity.status(HttpStatus.CREATED).body(result);
    }
}

Pagination, filtering, and sorting

Never return an unbounded collection. If GET /orders dumps a million orders at once, both your server and the client choke. You must paginate. There are two main approaches.

offset versus cursor

The cursor logic rests on this: instead of "skip 20," you say "give me all rows whose id is greater than the last id of the previous page." Because you jump on an indexed column, the speed stays constant.

// Keyset-based cursor: get the next page from the last row's id
@GetMapping("/orders")
public PageResponse<Order> list(
        @RequestParam(required = false) Long after,
        @RequestParam(defaultValue = "20") int limit) {

    int capped = Math.min(limit, 100); // always set a cap!
    List<Order> rows = (after == null)
        ? repo.findFirstPage(capped + 1)          // fetch one extra
        : repo.findAfter(after, capped + 1);      // to know if a next page exists

    boolean hasNext = rows.size() > capped;
    if (hasNext) rows.remove(rows.size() - 1);    // drop the extra row

    Long nextCursor = hasNext ? rows.get(rows.size() - 1).id() : null;
    return new PageResponse<>(rows, nextCursor);
}

Filtering and sorting

Do filtering and sorting with query parameters, not by building separate endpoints:

GET /orders?status=SHIPPED&minTotal=100&sort=createdAt,desc

Error format: the problem+json standard

The biggest inconsistency in APIs is the error format. Every team invents its own shape: one uses {"error": "..."}, another {"message": "...", "code": 42}, another raw text. The consumer has to relearn it for each API. This is where a standard saves you.

The original standard was RFC 7807 (2016), which was revised and superseded by RFC 9457 (published July 2023). RFC 9457 subsumes all of RFC 7807 and adds a few improvements (like better support for "multiple problems at once" and a shared registry of problem types). The Content-Type for these responses is application/problem+json. The standard fields:

• type: a URI that identifies the type of problem (e.g. a link to that error's docs).
• title: a short, human-readable summary of the problem type.
• status: the HTTP status code, echoed in the body.
• detail: a human explanation specific to this occurrence.
• instance: a URI that identifies this particular occurrence.
• Plus any extension fields you like (e.g. errors for validation details).

Good news for Java folks: since Spring Boot 3.0, this standard is supported natively through the ProblemDetail class. You just flip a property or extend ResponseEntityExceptionHandler.

// Option 1: enable globally in application.properties
// spring.mvc.problemdetails.enabled=true

// Option 2: handle errors manually with ProblemDetail
@RestControllerAdvice
public class ApiExceptionHandler {

    @ExceptionHandler(OrderNotFoundException.class)
    public ProblemDetail handleNotFound(OrderNotFoundException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(
                HttpStatus.NOT_FOUND, ex.getMessage());
        pd.setType(URI.create("https://api.example.com/errors/order-not-found"));
        pd.setTitle("Order Not Found");
        pd.setInstance(URI.create("/orders/" + ex.getOrderId()));
        pd.setProperty("orderId", ex.getOrderId()); // extension field
        pd.setProperty("timestamp", Instant.now());
        return pd; // Spring sets Content-Type to application/problem+json
    }
}

The produced response looks like this:

{
  "type": "https://api.example.com/errors/order-not-found",
  "title": "Order Not Found",
  "status": 404,
  "detail": "No order exists with id 8801",
  "instance": "/orders/8801",
  "orderId": 8801,
  "timestamp": "2026-07-20T10:15:30Z"
}

HATEOAS: REST's most ambitious part

HATEOAS stands for Hypermedia As The Engine Of Application State — Level 3 of the Richardson model.

For example, an order's response gives different links depending on its state:

{
  "id": 8801,
  "status": "PENDING",
  "total": 250.00,
  "_links": {
    "self":   { "href": "/orders/8801" },
    "cancel": { "href": "/orders/8801/cancel", "method": "POST" },
    "pay":    { "href": "/orders/8801/payment", "method": "POST" }
  }
}

If the order had already been paid, the pay link would no longer appear. That is, the server tells the client "which actions are legal right now" and the client doesn't have to duplicate the state logic inside itself. In Spring, the Spring HATEOAS library builds these links with EntityModel and WebMvcLinkBuilder.

Versioning and backward compatibility

This is the most serious senior part of API design. The moment the first client connects to your API, you no longer "freely own" your contract; you are responsible to that client.

Breaking versus non-breaking changes

First you must know what breaks a client:

• Non-breaking (backward-compatible): adding a new optional field, adding a new endpoint, adding a new value to an output enum (carefully). An old client ignores these and keeps working.
• Breaking: removing or renaming a field, changing a field's type (string to number), making a previously optional input field required, changing the meaning of a status code, tightening validation rules.

Four versioning strategies

In practice, URI-path versioning (like /v1/...) is the most common and pragmatic choice, because it's transparent and everyone understands it. Hardcore REST purists consider media-type versioning "more correct," but its operational cost is high.

OpenAPI and contract-first design

Now we reach the tool that ties all of this into one formal document: OpenAPI.

OpenAPI (formerly called Swagger) is the dominant standard for describing REST APIs. The versions:

• OpenAPI 3.1 (February 2021): a major milestone — the first version to become fully aligned with JSON Schema (draft 2020-12). That means the very schema you use to validate data is directly usable in the API description.
• OpenAPI 3.2 (September 2025): the newest release; additions like structured tag navigation, streaming-friendly media types, and fresh OAuth flows on top of that JSON-Schema-aligned foundation.

Two styles: code-first and contract-first

In the Java world the popular library is springdoc-openapi, which auto-generates the OpenAPI document and the interactive Swagger UI from Spring annotations. A current note: since version 2.8.0, springdoc produces OpenAPI 3.1 by default.

// A code-first example with springdoc-openapi
@RestController
@RequestMapping("/api/v1/orders")
@Tag(name = "Orders", description = "Order management")
public class OrderController {

    @Operation(summary = "Read an order by id")
    @ApiResponses({
        @ApiResponse(responseCode = "200", description = "Order found"),
        @ApiResponse(responseCode = "404", description = "Order does not exist",
            content = @Content(mediaType = "application/problem+json"))
    })
    @GetMapping("/{id}")
    public Order getOrder(
            @Parameter(description = "The order id") @PathVariable Long id) {
        return service.findById(id);
    }
}

And as soon as you add the springdoc-openapi-starter-webmvc-ui dependency, live docs come up at /swagger-ui.html and the raw document at /v3/api-docs.

But in the contract-first style, you write the OpenAPI file first:

openapi: 3.1.0
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders/{id}:
    get:
      operationId: getOrder
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Problem' }
components:
  schemas:
    Order:
      type: object
      required: [id, status, total]
      properties:
        id:     { type: integer, format: int64 }
        status: { type: string, enum: [PENDING, PAID, SHIPPED] }
        total:  { type: number }

Then, with a tool like OpenAPI Generator, this file produces both the server-side interfaces (that your code must implement) and ready-made clients for various languages.

Rate limiting: protecting the server from a flood of requests

When a client exceeds its quota, the correct status code is 429 Too Many Requests. But merely rejecting is not enough; you must tell the client "how much is left" and "when to retry." For this, an IETF draft named draft-ietf-httpapi-ratelimit-headers is standardizing the headers:

• RateLimit: the current quota status (how much is left and when it resets).
• RateLimit-Policy: the quota policy the server advertises.
• And on a 429 response, the standard Retry-After header telling how many seconds to wait.

@Component
public class RateLimitFilter extends OncePerRequestFilter {

    private final RateLimiter limiter; // e.g. token-bucket on Redis

    @Override
    protected void doFilterInternal(HttpServletRequest req,
            HttpServletResponse res, FilterChain chain)
            throws ServletException, IOException {

        String clientId = resolveClient(req); // by API key or IP
        Quota quota = limiter.tryConsume(clientId);

        res.setHeader("RateLimit-Remaining", String.valueOf(quota.remaining()));
        res.setHeader("RateLimit-Reset", String.valueOf(quota.resetSeconds()));

        if (!quota.allowed()) {
            res.setStatus(429);
            res.setHeader("Retry-After", String.valueOf(quota.resetSeconds()));
            res.setContentType("application/problem+json");
            res.getWriter().write("""
                {"type":"about:blank","title":"Too Many Requests","status":429}""");
            return;
        }
        chain.doFilter(req, res);
    }
}

Authentication: API keys versus OAuth

The last design piece is who can touch your API. Two common approaches:

A current note on OAuth: OAuth 2.1 (still a draft but practically adopted — even Anthropic's MCP protocol is built on it) makes several security decisions that were previously "recommended" now mandatory:

• PKCE for all clients became mandatory (previously recommended only for public clients).
• The implicit flow was removed entirely, because it exposed the token directly in the browser.
• The password grant (ROPC) was deprecated.
• The token must never go in a query string; only in the Authorization header.
• Exact redirect-URI matching (no wildcards).

Common pitfalls

Let's gather the top traps in one place — the ones that bite in interviews or real code:

• Verbs in the URI: /getUser, /createOrder — name the resource with a noun and leave the verb to HTTP.
• Everything 200: don't return errors with a 200 code and the message in the body; give the correct status code.
• Unbounded collections: without pagination, a GET /orders can knock over your server. Always set a cap.
• POST without idempotency: in money/order APIs, no Idempotency-Key means a double-charge on retry.
• Breaking change without versioning: removing or renaming a field in the existing version breaks production clients.
• Leaking internal details in errors: a stack trace in the response = an attack map for the attacker.
• sort straight into SQL: a door for SQL injection; always allow-list.
• API key in the query string: it lingers in logs and browser history; put it in a header.

Best practices

• Model resources with plural nouns (/users, not /user or /getUser) and use HTTP verbs correctly.
• Choose status codes precisely; especially 201 with a Location header, and the 401/403 and 400/422 distinctions.
• Standardize errors with application/problem+json (RFC 9457); in Spring Boot 3 use ProblemDetail.
• Prefer cursor pagination for collections, always with a capped limit.
• Evolve with the additive, not subtractive principle to reduce the need for new versions; version the whole API path.
• Document the API with OpenAPI; for multi-team collaboration consider contract-first.
• Put rate limiting and proper auth (API key for server-to-server, OAuth 2.1 for users) in place from day one.

Interview Questions

Now it's time to test everything through real senior-interview questions. Answer each yourself first, then open the answer.