URI Design Rules & Guidelines
URI Design Rules & Guidelines
Section titled “URI Design Rules & Guidelines”Follow these rules when designing resource URIs:
1. Use Forward Slash for Hierarchy
Section titled “1. Use Forward Slash for Hierarchy”The forward slash (/) indicates a hierarchical relationship between resources.
# Good/universities/123/departments/456/courses
# The hierarchy: university → department → courses2. Use Hyphens for Readability
Section titled “2. Use Hyphens for Readability”Hyphens (-) improve URI readability for multi-word resource names.
# Good/api/user-profiles/api/order-items
# Bad/api/userprofiles/api/orderitems3. Avoid Underscores
Section titled “3. Avoid Underscores”Underscores (_) can be hidden by underline styling in links. Use hyphens instead.
# Good/api/blog-posts
# Bad/api/blog_posts4. Use Lowercase Letters
Section titled “4. Use Lowercase Letters”URIs are case-sensitive. Use lowercase to avoid confusion.
# Good/api/users/123/orders
# Bad/api/Users/123/Orders5. Singular for Document Names
Section titled “5. Singular for Document Names”Use singular nouns for singleton resources (specific documents).
# Good - singular for specific item/api/users/123/profile/api/planets/earth/atmosphere
# These represent ONE thing, not a collection6. Plural for Collections
Section titled “6. Plural for Collections”Use plural nouns for collection resources.
# Good/api/books/api/users/api/orders
# Bad/api/book/api/user/api/order7. Use Identity-Based Path Segments
Section titled “7. Use Identity-Based Path Segments”Variable path segments should contain resource identifiers.
# Good - ID identifies the spescific resource/api/books/978-0-13-468599-1/api/users/john-doe/api/orders/ORD-2024-0018. No CRUD Names in URIs
Section titled “8. No CRUD Names in URIs”HTTP methods already indicate the operation. Don’t repeat it in the URI.
# Good - HTTP verb indicates actionGET /api/books/123POST /api/booksPUT /api/books/123DELETE /api/books/123
# Bad - redundant action wordsGET /api/getBook/123POST /api/createBookPUT /api/updateBook/123DELETE /api/deleteBook/1239. No Trailing Slashes
Section titled “9. No Trailing Slashes”Trailing slashes add no semantic value and can cause confusion or duplicate resources.
# Good/api/books/123
# Bad/api/books/123/10. No File Extensions
Section titled “10. No File Extensions”Use content negotiation (Accept header) instead of file extensions. This keeps URIs clean and flexible.
# Good - use Accept header for formatGET /api/books/123Accept: application/json
# Bad - format in URI/api/books/123.json/api/books/123.xml11. Use Query Parameters for Filtering, Sorting, and Pagination
Section titled “11. Use Query Parameters for Filtering, Sorting, and Pagination”Path segments define resource hierarchy. Query strings handle filtering, sorting, and pagination.
# Good - query parameters for non-hierarchical data/api/books?author=tolkien&sort=title&page=2&limit=20
# Bad - filtering in path segments/api/books/author/tolkien/sort/title/page/212. Avoid Deep Nesting
Section titled “12. Avoid Deep Nesting”Limit hierarchy depth to 2-3 levels for readability. Flatten deep hierarchies using query parameters.
# Good - flattened with query parameter/api/courses?department=456
# Acceptable - shallow nesting (2 levels)/api/universities/123/departments
# Avoid - too deep (4+ levels)/api/universities/123/departments/456/professors/789/courses13. Consider API Versioning Strategy
Section titled “13. Consider API Versioning Strategy”If versioning via URI, place the version at the start of the path.
# URI versioning/v1/api/books/v2/api/books
# Alternative: Header versioning (keeps URIs clean)GET /api/booksApi-Version: 2