Conventions for REST URIs

Acronym

conventions-for-rest-uris

Belongs to

SIG

Responsible

Tobi

History

(v1)   2021-10-08 - created initially

(v2)   2021-10-22 - Add convention draft

(v3)   2021-11-09 - No further comments -> agreed

Why is there need for such a decision?

All REST APIs in this applications should have a similar structure.

Additional sources for better understanding the background

• Adidas API Guidelines
• Zalando API Guidelines
• Microsoft API Guidelines
• Best Practices in API Design
• RESTful web API Design

Viable Options

n/a, see resolution

Alternatives not seriously considered

n/a, see resolution

How is this decision evaluated?

No evaluation needed.

Resolution details

Structure the API around resources of our business entities

• GOOD ✅: /users/{id}/groups
• BAD ❌: /get-users/user-by-id/{id}?q=groups

No Verbs

• GOOD ✅: POST /users
• BAD ❌: POST /users/create-new

Use plural nouns for collectional resources

• GOOD ✅: GET /users/{id}
• BAD ❌: GET /user/{id}

Keep the URIs flat and unnested

• BAD ❌: /users/{id}/groups/{id}/roles/{id}

However keep in mind, that it might be necessary to use nested URIs when a subresource is only accessable via its parent.

Normalize the URIs (No trailing slash, no double-slash)

• BAD ❌: /users//{id}
• BAD ❌: /users//{id}/

Use kebab-case to improve readability

• GOOD ✅: /shopping-cart
• BAD ❌: /shopping_cart
• BAD ❌: /shoppingCart
• BAD ❌: /sHoPpInGcArT

Don’t use matrix parameters, use query parameters

• GOOD ✅: /products?sort=price
• BAD ❌: /products;sort=price

Use multiple query parameters (also known as explode)

• GOOD ✅: /products?sort=price&sort=color
• BAD ❌: /products?sort=price,color

Reasons for the resolution

• Some aspects are well-defined by the REST paradigma itself and therefore mandatory
• Some aspects are best practices
• And some aspects are a matter of taste but have to be decided in order to have a consistent API