REST API Cheatsheet

What is REST?

REST (Representational State Transfer) is an architectural style for web services that uses HTTP to access and manipulate resources. Introduced by Roy Fielding in 2000.

Principle	Description
Client-Server	Clear separation between client and server
Stateless	Each request contains all needed information
Cacheable	Responses marked as cacheable or non-cacheable
Uniform Interface	Standard methods, consistent resource URIs
Layered System	Can include proxies, gateways, load balancers
Code on Demand	Server can send executable code (optional)

---

What is a REST API?

A REST API is modeled as collections of individually-addressable resources, which are:

• Nouns of the API (e.g., books, users, orders)
• Referenced by URIs (resource names)
• Manipulated via HTTP methods: GET, POST, PUT, PATCH, DELETE

---

Resources

Resources are the nouns of your API: the “things” your system manages (books, users, orders). The URL identifies what (the resource), the HTTP verb specifies what to do with it.

Type	Description	Example
Singleton	Single specific instance	/planets/mars
Collection	Group of same-type resources	/planets
Sub-collection	Collection under a parent	/planets/mars/moons

---

API Design Workflow

Follow these 6 steps to design a REST API:

1. Identify Resources: Extract nouns from your domain
2. Determine Types: Singleton, collection, or sub-collection?
3. Define Relationships: Sub-resources vs references
4. Design URLs: Plural nouns, lowercase, hyphens
5. Map HTTP Methods: CRUD operations to verbs
6. Design Responses: JSON structure with _links

---

URL Naming Rules

• Use plural nouns: /planets, /missions
• Use lowercase with hyphens: /space-stations
• No verbs in URLs: /missions, not /getMissions
• Keep hierarchy shallow (2-3 levels max)

/api/missions                    # Collection
/api/missions/{id}               # Singleton
/api/missions/{id}/crew          # Sub-collection
/api/missions/{id}/crew/{id}     # Singleton in sub-collection

---

HTTP Verbs

HTTP methods (verbs) define what action to perform on a resource. The URL identifies the resource; the verb says what to do with it.

Key concepts:

• Idempotent: Same request multiple times = same result (safe to retry)
• Safe: Doesn’t modify server state (read-only)

Method	Purpose	Idempotent	Safe	Request Body
GET	Retrieve	Yes	Yes	No
POST	Create	No	No	Yes
PUT	Replace entire	Yes	No	Yes
PATCH	Partial update	Yes*	No	Yes
DELETE	Remove	Yes	No	No

*PATCH is idempotent when implemented correctly

Verb Usage Matrix

Endpoint	GET	POST	PUT	PATCH	DELETE
/resources	List all	Create new	N/A	N/A	N/A
/resources/{id}	Get one	N/A	Replace	Update	Remove

Common mistakes to avoid:

• Using GET for operations that modify data
• Using POST for everything instead of proper verbs

---

Status Codes

Status codes indicate the outcome of a request:

• 2xx: Success
• 4xx: Client error (your fault)
• 5xx: Server error (our fault)

Code	Meaning
200	OK: Request successful
201	Created: Resource created
204	No Content: Success, no body
400	Bad Request: Invalid data
404	Not Found: Resource doesn’t exist

For complete status codes, see HTTP Status Codes.

---

Response Format

Include essential fields and navigation links:

{
  "id": "apollo-11",
  "name": "Apollo 11",
  "status": "completed",
  "launch_date": "1969-07-16",
  "_links": {
    "self": "/api/missions/apollo-11",
    "crew": "/api/missions/apollo-11/crew"
  }
}

Guidelines:

• Include only essential fields
• Add _links for navigation (HATEOAS)
• Use pagination for collections
• Keep consistent structure across resources

---

Quick Decision Guide

Scenario	Resource Type
Single configuration/settings	Singleton
List of similar items	Collection
Items belonging to a parent	Sub-collection
One-to-one relationship	Singleton sub-resource
One-to-many relationship	Sub-collection

When to use sub-resources: If deleting the parent should delete the child, use sub-resources. Otherwise, use references.

---

See Also

• Introduction to REST
• Resource-Oriented Design
• Designing REST APIs
• HTTP Verbs
• HTTP Status Codes