Designing REST APIs

Why Learn REST API Design?

Imagine you’re organizing a library. You need to decide:

• What things do we have? (books, members, loans)
• How do we organize them? (by category, alphabetically)
• How do people find what they need? (catalog system, clear signs)

Designing a REST API is exactly the same! You’re creating an organized system that lets other programs find, create, update, and delete data in your application.

By the end of this guide, you’ll be able to:

• Identify the “things” (resources) in any system
• Organize them into logical URL structures
• Connect them with the right HTTP operations
• Design responses that are easy to understand and navigate

---

The Design Workflow

REST API design is about modeling your domain as resources (nouns), not actions (verbs). Follow these 6 steps to design a clean, intuitive API.

---

Step 1: Identify Resources

Look at your domain and extract the nouns—the “things” your system manages.

Think Like a Video Game Designer

When identifying resources, ask yourself: “What are all the things in my system?”

Just like in a video game you’d list characters, items, levels, and scores—in an API, you list the data objects your system manages.

Example Domain: Space Mission Management

“Space agencies plan missions to planets. Astronauts are assigned to missions and use spacecraft to collect scientific data.”

Let’s circle all the nouns: Space agencies plan missions to planets. Astronauts are assigned to missions and use spacecraft to collect scientific data.

Resources identified:

• Mission — A space expedition
• Astronaut — A crew member
• Planet — A celestial body
• Spacecraft — A vehicle
• Data — Scientific information collected

Avoid action-oriented thinking:

Wrong (verbs)	Right (nouns)
getMission	Mission
createAstronaut	Astronaut
launchSpacecraft	Spacecraft

Remember

HTTP already gives us verbs (GET, POST, PUT, DELETE). Your job is just to name the things—the nouns!

---

Step 2: Determine Resource Types

Classify each resource. Think of it like a library:

Type	Analogy	Example
Singleton	ONE specific book by title	/api/missions/apollo-11
Collection	ALL books in a section	/api/missions
Sub-Collection	All chapters IN a book	/api/missions/apollo-11/crew

GET /api/planets          # Collection: all planets
GET /api/planets/mars     # Singleton: one planet
GET /api/planets/mars/moons  # Sub-collection: moons of Mars

For detailed explanations of each resource type, see Resource-Oriented Design.

---

Step 3: Define Relationships

Decide how resources connect to each other:

Approach	When to Use	Example
Sub-resources	Child depends on or belongs to parent	/missions/apollo-11/crew
References	Resources exist independently	"mission_id": "apollo-11" with _links

Quick decision: If deleting the parent should delete the child, use sub-resources. If not, use references.

# Sub-resource: crew only exists within a mission
GET /api/missions/apollo-11/crew

# Reference: astronauts exist independently, linked via ID
GET /api/astronauts/neil-armstrong
# Response includes: { "current_mission": "apollo-11", "_links": { ... } }

For more on relationship types, see Resource-Oriented Design.

---

Step 4: Design URL Structure

Good URLs should read almost like a sentence.

The Sentence Test

/api/missions/apollo-11/crew reads as: “Get me the crew of mission apollo-11”

If your URL reads naturally, you’re on the right track!

Naming Conventions

• Plural nouns for collections: /planets, /missions
• Lowercase with hyphens: /space-stations, not /spaceStations
• No verbs in URLs: /missions, not /getMissions
• Identifiers for singletons: /missions/apollo-11

Why Hyphens?

Computers don’t like spaces in URLs. Hyphens act like spaces for readability: space-stations is much easier to read than spacestations.

URL Hierarchy

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

Keep It Shallow

# Good: Max 2 levels deep
GET /api/missions/apollo-11/crew

# Avoid: Too deep, hard to use
GET /api/missions/apollo-11/crew/neil/training/physical/cardio

If you need deep data, provide it as a direct resource:

GET /api/astronauts/neil/training

---

Step 5: Map HTTP Operations

Map each resource to the HTTP methods it supports:

Resource	GET	POST	PUT/PATCH	DELETE
/missions	List all	Create new	—	—
/missions/{id}	Get one	—	Update	Delete
/missions/{id}/crew	List crew	Add member	—	—
/missions/{id}/crew/{id}	Get member	—	Update role	Remove

HTTP Methods as Library Actions

• GET → “Show me” (looking up a book)
• POST → “Create new” (adding a book)
• PUT/PATCH → “Update” (changing book info)
• DELETE → “Remove” (removing a book)

For detailed HTTP method semantics, see HTTP Verbs. For status codes, see HTTP Status Codes.

---

Step 6: Design Response Format

Keep Responses Concise

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

What Are _links?

Think of _links as a “See Also” section at the bottom of a Wikipedia article. They help API users navigate to related resources without memorizing URLs.

Instead of the client having to know that crew is at /api/missions/apollo-11/crew, the response just tells them: “Hey, if you want the crew, here’s the link!”

Collection Response with Pagination

{
  "page": 1,
  "limit": 10,
  "total_count": 156,
  "missions": [
    { "id": "apollo-11", "name": "Apollo 11", "status": "completed" },
    { "id": "artemis-3", "name": "Artemis 3", "status": "planned" }
  ],
  "_links": {
    "self": "/api/missions?page=1",
    "next": "/api/missions?page=2"
  }
}

Response Guidelines

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

---

Quick Reference Checklist

Use this checklist when designing your API:

Step	Check
1. Resources	Identified all nouns in your domain?
2. Types	Singleton, Collection, or Sub-collection?
3. Relationships	Dependencies mapped? Sub-resources vs references decided?
4. URLs	Plural nouns? Lowercase with hyphens? Shallow hierarchy?
5. Operations	HTTP methods mapped correctly? Status codes defined?
6. Responses	Concise? Links included? Pagination for collections?

---

Example: Complete API Design

Domain: Space Mission Management

Resources:
├── /api/missions                    # All missions
│   └── /{id}                        # Single mission
│       ├── /crew                    # Mission crew (sub-collection)
│       └── /data                    # Mission data (sub-collection)
├── /api/astronauts                  # All astronauts (independent)
│   └── /{id}
│       └── /missions                # Astronaut's mission history
├── /api/planets                     # All planets
│   └── /{id}
│       └── /moons                   # Planet's moons (sub-collection)
└── /api/spacecraft                  # All spacecraft (independent)