7 Rules for Designing REST API URIs

Before discussing the rules, the article introduces key terms such as URI and its role in addressing resources in a REST API.

Rule 1: No trailing slash – A trailing slash adds no semantic value and can cause confusion; APIs should not expect or return it.

Example: http://api.canvas.com/shapes/ vs http://api.canvas.com/shapes are treated as distinct resources.

Rule 2: Use forward slash (/) to indicate hierarchy – The slash separates hierarchical levels, e.g., http://api.canvas.com/shapes/polygons/quadrilaterals/squares.

Rule 3: Use hyphens (-) for readability – Replace spaces with hyphens in path segments, e.g.,

http://api.example.com/blogs/guy-levin/posts/this-is-my-first-post

.

Rule 4: Avoid underscores (_) – Underscores can be hidden by browsers; hyphens are preferred.

Rule 5: Prefer lowercase letters in paths – Uppercase letters may cause issues; paths are case‑sensitive except for scheme and host.

Rule 6: Do not include file extensions – The format should be negotiated via the Accept header, not by appending extensions such as .json.

Example:

http://api.college.com/students/3248234/courses/2005/fall.json

should be http://api.college.com/students/3248234/courses/2005/fall.

Rule 7: Use plural nouns for endpoint names – Consistently use plural forms (e.g., /students, /students/3248234/courses) to simplify routing and client expectations.

Conclusion: Well‑designed URIs clearly convey the resource model, follow a predictable hierarchical structure, and improve API usability for consumers.