Designing REST APIs · Lesson 4 of 30
REST API Design Best Practices: Resources and URLs
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
| Avoid | Prefer |
|---|---|
GET /getCourses | GET /courses |
POST /createCourse | POST /courses |
POST /courses/react/delete | DELETE /courses/react |
GET /course/react (singular) | GET /courses/react (collection, then item) |
GET /Courses_List | lowercase, 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
- /courses/{courseId} – one course
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);
$ 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/lessonsshould 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/2can 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:
| Approach | Example | When |
|---|---|---|
| Update a field | PATCH /courses/react with {"status":"published"} | the action is just a state change |
| Create a sub-resource | POST /orders/7/cancellation | the action has its own data (reason, who, when) |
| Action endpoint | POST /invoices/42/send | a 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) orsnake_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
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.