Endpoint

A complete endpoint URL has these parts:

https://api.example.com/v1/users/123?include=orders

Collection endpoints - operate on groups:

• GET /users - List all users
• POST /users - Create a new user

Resource endpoints - operate on single items:

• GET /users/123 - Get specific user
• PUT /users/123 - Replace user
• PATCH /users/123 - Update user fields
• DELETE /users/123 - Remove user

Nested endpoints - show relationships:

• GET /users/123/orders - Orders belonging to user 123
• POST /users/123/orders - Create order for user 123

Action endpoints - for non-CRUD operations:

• POST /users/123/reset-password - Trigger password reset
• POST /orders/456/cancel - Cancel an order

Use nouns, not verbs: The HTTP method is the verb. The URL is the noun.

• ✅ POST /users (create user)
• ❌ POST /createUser

Use plural names: Collections are plural, even for single resources.

• ✅ GET /users/123
• ❌ GET /user/123

Use kebab-case: Lowercase with hyphens for multi-word resources.

• ✅ /user-profiles
• ❌ /userProfiles or /user_profiles

Keep it shallow: Deep nesting becomes unwieldy. Max 2-3 levels.

• ✅ /users/123/orders
• ❌ /users/123/orders/456/items/789/reviews

Use query params for filtering: Don't encode filters in the path.

• ✅ /users?status=active&role=admin
• ❌ /users/active/admin

Use query params for:

Filtering: /products?category=electronics&price_max=100 Sorting: /users?sort=created_at&order=desc Pagination: /posts?page=2&limit=20 Field selection: /users?fields=id,name,email Including relations: /orders?include=items,customer Searching: /products?q=laptop

APIs change. Versioning prevents breaking existing clients.

URL versioning (most common): /v1/users, /v2/users

Header versioning: Accept: application/vnd.api.v1+json

Query param versioning: /users?version=1

Start with v1 even if you don't plan v2. It's easier to add than retrofit.

1. Inconsistent naming: /users, /Product, /order-items, /customerAddress Pick one convention and stick to it across all endpoints.

2. Verbs in URLs: /getUsers, /deleteUser/123, /createOrder Let HTTP methods be the verbs.

3. Exposing implementation details: /api/mysql/users/select Clients don't care about your database.

4. Not using proper status codes: GET /users/999 returning 200 with empty body instead of 404.

5. Ignoring trailing slashes: /users and /users/ should behave the same. Pick one and redirect the other.

Be consistent: If /users returns a list, /products should too. Same patterns everywhere.

Use meaningful names: /api/v1/u/123 is cryptic. /api/v1/users/123 is clear.

Document every endpoint: Method, URL, parameters, request body, response format, possible errors.

Return useful errors: When an endpoint fails, tell the client why. {"error": "email already exists", "field": "email"}

Consider rate limiting: Protect endpoints from abuse. Return 429 with Retry-After header.