REST OpenAPI — Cheat Sheet

Tags: rest, openapi, swagger, api-design, http, json-schema

Level: intermediate

TL;DR: Quick reference for REST architectural constraints, HTTP semantics, and OpenAPI 3.x contract-first design.

Key concepts

REST is an architectural style based on stateless client-server interactions and standard HTTP methods.

Resources are uniquely identified by URIs and manipulated via standard representations (JSON, XML).

GET, HEAD, OPTIONS are safe and idempotent; PUT and DELETE are idempotent; POST and PATCH are non-idempotent.

Use plural nouns for resource endpoints (/users, /orders) and avoid verbs in URI paths.

OpenAPI Specification (OAS) 3.x defines a machine-readable, vendor-neutral standard for RESTful APIs.

Core OAS sections include openapi, info, servers, paths, components, and security.

Reusable schemas, parameters, responses, and security schemes belong in components.

Use $ref: '#/components/schemas/Name' to eliminate schema duplication.

Contract-first design drives mock servers, automated testing, client SDK generation, and runtime validation.

Path parameters identify resources (/orders/{id}); query parameters filter, sort, or paginate (/orders?status=open).

Typical questions and ready answers

Q: What is the difference between PUT and PATCH in REST?R: I use PUT to completely replace a target resource representation, while PATCH applies a partial set of changes or modifications to the existing resource.

Q: Why choose a contract-first approach with OpenAPI over code-first?R: Defining the OpenAPI spec first creates a single source of truth, unlocks early client/backend parallel development via mocks, and avoids implementation leakage into public API contracts.

Q: How do you handle pagination and versioning cleanly in REST APIs?R: I prefer URI path versioning like /v1/resources for major breaking changes, and standard query parameters (limit, offset, or cursor tokens) paired with total count metadata in responses.

Pitfalls and common mistakes

Using verbs in endpoint URIs (e.g., /getUserById, /createOrder) instead of nouns combined with standard HTTP verbs.

Returning 200 OK when an error occurs instead of returning proper 4xx/5xx HTTP status codes.

Failing to mark required fields explicitly under required arrays in OpenAPI schema definitions.

Confusing 401 Unauthorized (unauthenticated/missing credentials) with 403 Forbidden (authenticated but lacks permissions).

Neglecting to define error payloads in OpenAPI contracts, leaving clients to guess error schema shapes.

Snippets and commandsYAML

```openapi: 3.0.3

info:

title: Orders API

version: 1.0.0

paths:

/orders/{orderId}:

get:

summary: Get order by ID

parameters:

• name: orderId

in: path

required: true

schema:

type: string

format: uuid

responses:

'200':

description: Order retrieved

content:

application/json:

schema:

$ref: '#/components/schemas/Order'

'404':

description: Order not found

components:

schemas:

Order:

type: object

required:

• id
• total

properties:

id:

type: string

format: uuid

total:

type: number

format: float

```

To review

[ ] Differentiate HATEOAS level 3 Richardson Maturity Model trade-offs from practical REST design

[ ] Understand OAuth2 and Bearer token wiring in OpenAPI securitySchemes

[ ] Handle multipart file upload representations in OpenAPI 3.x

[x] Correct usage of standard HTTP status codes (201 Created, 204 No Content, 400 Bad Request)