LearnFrenzy
Sign in Take a free test

Designing REST APIs · Lesson 4 of 30

REST API Design Best Practices: Resources and URLs

4 min read Updated Nov 8, 2026 Saurabh Samir

An API's URLs are its user interface for developers. Good ones are predictable: once someone has seen GET /api/courses, they can guess GET /api/courses/react and GET /api/courses/react/lessons without reading the docs. This lesson gives you the naming rules that well-known APIs (Stripe, GitHub, Shopify) follow, and the reasoning behind them.

In this lesson

  • Resources are nouns; methods are the verbs
  • Collections, items and nesting
  • Query parameters vs path segments
  • Handling actions that aren't CRUD

Nouns in the URL, verbs in the method

AvoidPrefer
GET /getCoursesGET /courses
POST /createCoursePOST /courses
POST /courses/react/deleteDELETE /courses/react
GET /course/react (singular)GET /courses/react (collection, then item)
GET /Courses_Listlowercase, hyphens: /learning-paths

A resource hierarchy

  • /courses – the collection
    • /courses/{courseId} – one course
      • /courses/{courseId}/lessons – its lessons
      • /courses/{courseId}/lessons/{lessonId} – one lesson
      • /courses/{courseId}/enrolments – who's enrolled

Collections, items and nesting in code

// server.js
import express from 'express';

const app = express();

const courses = [
  { id: 'rest-api', title: 'REST API & Web Services', level: 'intermediate' },
  { id: 'react', title: 'React.js', level: 'beginner' },
];
const lessons = [
  { id: 1, courseId: 'rest-api', title: 'What Is a REST API?' },
  { id: 2, courseId: 'rest-api', title: 'How HTTP Works' },
  { id: 3, courseId: 'react', title: 'What Is React?' },
];

app.get('/api/courses', (req, res) => {
  const { level } = req.query;                                      // filter with a query parameter
  res.json(level ? courses.filter((c) => c.level === level) : courses);
});

app.get('/api/courses/:courseId', (req, res) => {
  const course = courses.find((c) => c.id === req.params.courseId);
  if (!course) return res.status(404).json({ error: 'Course not found' });
  res.json(course);
});

app.get('/api/courses/:courseId/lessons', (req, res) => {            // a sub-collection
  if (!courses.some((c) => c.id === req.params.courseId)) return res.status(404).json({ error: 'Course not found' });
  res.json(lessons.filter((l) => l.courseId === req.params.courseId));
});

app.listen(process.env.PORT ?? 3000);

Real responses

$ curl 'http://localhost:3000/api/courses?level=beginner'
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "id": "react",
    "title": "React.js",
    "level": "beginner"
  }
]

$ curl http://localhost:3000/api/courses/rest-api/lessons
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "id": 1,
    "courseId": "rest-api",
    "title": "What Is a REST API?"
  },
  {
    "id": 2,
    "courseId": "rest-api",
    "title": "How HTTP Works"
  }
]

$ curl http://localhost:3000/api/courses/vue/lessons
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error": "Course not found"
}
  • Use path segments for identity and hierarchy (which course, its lessons).
  • Use query parameters for anything optional that narrows or shapes the result: filters, search, sorting, pagination, field selection.
  • Check that the parent exists: /courses/vue/lessons should be 404, not an empty list that hides a typo.
  • Keep nesting shallow – one level is usually enough. A lesson has its own id, so /lessons/2 can work too; don't build /schools/1/courses/2/lessons/3/comments/4.

Actions that aren't CRUD

Some operations don't map neatly to create/read/update/delete: publishing a course, cancelling an order, resending an email. Three common, respectable options:

ApproachExampleWhen
Update a fieldPATCH /courses/react with {"status":"published"}the action is just a state change
Create a sub-resourcePOST /orders/7/cancellationthe action has its own data (reason, who, when)
Action endpointPOST /invoices/42/senda pure command with side effects; used by Stripe, GitHub and others

Consistency rules

  • Plural nouns for collections, lowercase, hyphens between words: /learning-paths.
  • One JSON naming style for fields everywhere – camelCase (JavaScript clients) or snake_case (Stripe, GitHub). Pick one.
  • Stable, opaque ids in URLs (/orders/ord_8f3k2), not database row numbers you might change.
  • Version from day one: /api/v1/… or a header (covered in the versioning lesson).
  • No file extensions (/courses.json); use the Accept header for formats.

Practice

Try it yourself

  1. Design URLs for: listing a customer's invoices, getting invoice 42, marking it paid, and listing overdue invoices across all customers.

    Show solution
    GET   /api/customers/{customerId}/invoices
    GET   /api/invoices/42
    PATCH /api/invoices/42          {"status": "paid"}      # or POST /api/invoices/42/payments
    GET   /api/invoices?status=overdue

Quick check

Is /getUsers a good REST URL?

No – use GET /users; the method is the verb.

Filter by status: path or query?

Query: /orders?status=shipped.

How deep should nesting go?

Usually one level; give child resources their own top-level URLs when they have their own ids.

Summary

  • URLs name resources with plural nouns; HTTP methods are the verbs.
  • Paths for identity and hierarchy, query parameters for filters and options.
  • Handle non-CRUD actions with state fields, sub-resources or clear action endpoints – consistently.

Finished this lesson?

Mark it complete to track your progress, then carry on with the next lesson.

Next lesson

Search LearnFrenzy

Esc

Quick links