APIs · Lesson 4
Designing RESTful Endpoints
Modeling REST Resources
A REST API models resources rather than actions hidden in arbitrary URLs. Endpoint names should use stable nouns, and HTTP methods should express the operation. A consistent resource model reduces special cases for clients.
A Resource Representation
A response should contain identifiers and fields that are useful to the client without exposing persistence details. Java records are a compact way to model an API representation.
public record CourseResponse(long id, String slug, String title, int lessonCount) {
public static CourseResponse from(long id, String title, int lessonCount) {
String slug = title.toLowerCase().replace(' ', '-');
return new CourseResponse(id, slug, title, lessonCount);
}
public static void main(String[] arguments) {
System.out.println(CourseResponse.from(12, "Servlet Fundamentals", 12));
}
}
Endpoint Design Comparison
| Design | Prefer | Avoid |
|---|---|---|
| Collection | /courses | /getAllCourses |
| Item | /courses/12 | /courseById?id=12 |
| Nested relation | /courses/12/lessons | Deeply nested chains |
| Action | Method or subresource | Verb-heavy URLs everywhere |
Common Mistake and Practices
Common Mistake: Exposing database table names and internal joins as the public API model. Storage can change; an API contract should remain meaningful to clients.
- Use plural, stable resource names.
- Keep nesting shallow.
- Return representations tailored to the use case.
- Document filtering and sorting rules.
- Make update semantics explicit.
Real-World Use Case
A learning client loads /modules/core-java/lessons and /lessons/12/progress instead of depending on database terminology. The API can later change storage without forcing a mobile app rewrite.
Quiz Check