REST API Resource Naming and URL Design

/purchase-orders
/api-keys

# Pick one URL style and use it consistently.

Prefer: GET /reports/123
Avoid:  GET /reports/123.json

# Negotiate format via headers, not path suffixes.

GET /teams/{teamId}/members

# Make related collections obvious.

Better: /orders/{orderId}/items
Avoid:  /customers/{customerId}/orders/{orderId}/items/{itemId}/notes

# Prefer one or two levels of depth.

/orders/{orderId}
/order-items/{itemId}

# Each resource should have an obvious direct URL.

GET /users/123

# Use the path for the primary resource being addressed.

GET /users?role=admin&status=active

# Filter a collection with query fields.

GET /users/123?fields=id,name,email

# Return only needed fields.

GET /orders/ord_123?include=customer,items

# Let clients opt into embedded relationships.