URI Design and Naming

A developer meets BookNook for the first time and guesses: "books are probably at /v1/books, and book 42 at /v1/books/42." If they guess right, your API is well named. Every surprise, such as /v1/Book_List or /v1/getbook?id=42, costs them a trip to the docs and costs you a support question.

The rule

Plural nouns, lowercase, hyphens, no verbs — and pick one style forever.

The conventions most APIs follow:

• Plural nouns for collections: /books, /members, /loans. An item is the collection plus an id: /books/42.
• No verbs: the HTTP method is the verb. DELETE /books/42, not /books/42/delete.
• Lowercase with hyphens for multi-word path segments: /reading-lists, not /readingLists or /reading_lists. Paths can be case-sensitive, so mixing cases invites 404s.
• Shallow nesting: nest one level to show ownership, /members/7/loans. Past that, use top-level resources with filters: /loans?member_id=7&book_id=42, not /members/7/loans/901/books/42.
• No file extensions such as .json; use content negotiation.
• No trailing slash, or always one, but decide once and redirect the other.
• Stable ids: prefer ids that never change over names that might, like a title.

Consistency extends to the JSON too. Pick one field style, commonly snake_case or camelCase, and never mix them: due_date in one response and dueDate in another is a bug that looks like a feature.

Now and then an operation is not a noun at all, such as "recalculate all fines". A common compromise is a clearly named action sub-resource: POST /v1/fines/recalculations, which even gives you a record of each run.

The shortcut

Read the URL aloud as a path of nouns, from general to specific: "members → member 7 → their loans." If you have to say a verb, or the chain is longer than about two nouns, redesign it.

Drills

Answer fast — trust the rule.

Remember

• Plural nouns, lowercase, hyphens, no verbs — and one style forever.
• Shortcut: read the URL aloud as nouns from general to specific.
• Trap: verbs in paths, deep nesting, and mixed naming styles.