Dev REST API Design Guidelines

Create REST API design guidelines for [project/team].

API details:
- API type: [public/internal/partner]
- Auth method: [API key/OAuth/JWT]
- Version strategy: [URL/header/param]
- Response format: [JSON]
- Documentation tool: [OpenAPI/Swagger/Postman]

REST API DESIGN GUIDELINES

1. URL STRUCTURE

   RESOURCE NAMING
   - Use nouns not verbs: /users not /getUsers
   - Plural for collections: /users not /user
   - Lowercase with hyphens: /user-profiles
   - Nested for relationships: /users/{id}/orders

   GOOD EXAMPLES:
   GET /users — list users
   POST /users — create user
   GET /users/{id} — get user
   PUT /users/{id} — replace user
   PATCH /users/{id} — update user
   DELETE /users/{id} — delete user

2. HTTP METHODS
   - GET: retrieve (safe, idempotent)
   - POST: create (not idempotent)
   - PUT: replace entire resource
   - PATCH: partial update
   - DELETE: remove

3. STATUS CODES
   200 OK — successful GET/PUT/PATCH
   201 Created — successful POST
   204 No Content — successful DELETE
   400 Bad Request — invalid input
   401 Unauthorized — not authenticated
   403 Forbidden — authenticated but not authorized
   404 Not Found — resource does not exist
   409 Conflict — duplicate or state conflict
   422 Unprocessable Entity — validation errors
   429 Too Many Requests — rate limited
   500 Internal Server Error — server error

4. REQUEST AND RESPONSE FORMAT

   REQUEST BODY
   ```json
   {
     "firstName": "string",
     "email": "string"
   }
   ```

   SUCCESS RESPONSE
   ```json
   {
     "data": { },
     "meta": { "requestId": "uuid" }
   }
   ```

   ERROR RESPONSE
   ```json
   {
     "error": {
       "code": "VALIDATION_ERROR",
       "message": "Human readable message",
       "details": [ ]
     }
   }
   ```

5. PAGINATION
   - Cursor-based: [recommended for large datasets]
   - Offset-based: [simpler, for small datasets]
   
   Response include:
   ```json
   {
     "data": [],
     "pagination": {
       "cursor": "next_cursor",
       "hasMore": true,
       "total": 100
     }
   }
   ```

6. VERSIONING
   - URL versioning: /v1/users (recommended)
   - Deprecation policy: [support N-1 version]
   - Breaking changes: [new version required]
   - Non-breaking: [same version]

7. RATE LIMITING
   - Headers to include:
     X-RateLimit-Limit: 1000
     X-RateLimit-Remaining: 999
     X-RateLimit-Reset: [timestamp]