API design best practices define principles for creating clean, consistent, and developer-friendly interfaces — establishing conventions for endpoints, methods, error handling, versioning, and documentation that make APIs intuitive to use and maintainable long-term, especially important for LLM services where good design impacts developer experience and adoption.
Why API Design Matters
- Developer Experience: Good APIs are easy to understand and use.
- Adoption: Clean APIs encourage integration and usage.
- Maintenance: Consistent patterns reduce support burden.
- Evolution: Good versioning enables growth without breaking users.
- Scale: Well-designed APIs handle traffic and feature growth.
REST API Fundamentals
Resource-Based URLs:
``
Good:
GET /users # List users
GET /users/{id} # Get specific user
POST /users # Create user
PUT /users/{id} # Update user
DELETE /users/{id} # Delete user
Bad:
GET /getUsers
POST /createUser
POST /deleteUser/{id}
`
HTTP Methods:
`
Method | Purpose | Idempotent | Safe
--------|-----------------|------------|------
GET | Read resource | Yes | Yes
POST | Create resource | No | No
PUT | Replace/update | Yes | No
PATCH | Partial update | No* | No
DELETE | Remove resource | Yes | No
Response Codes:
`
Code | Meaning | When to Use
-----|----------------------|----------------------------
200 | OK | Successful GET, PUT, PATCH
201 | Created | Successful POST (resource created)
204 | No Content | Successful DELETE
400 | Bad Request | Invalid input from client
401 | Unauthorized | Missing/invalid auth
403 | Forbidden | Auth valid, but no permission
404 | Not Found | Resource doesn't exist
429 | Too Many Requests | Rate limited
500 | Internal Server Error| Server-side failure
LLM API Design Patterns
Chat Completions Pattern (OpenAI-style):
`json
POST /v1/chat/completions
{
"model": "gpt-4o",
"messages": [
{"role": "system", "content": "You are helpful."},
{"role": "user", "content": "Hello!"}
],
"temperature": 0.7,
"max_tokens": 1000,
"stream": false
}
Response:
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1677652288,
"model": "gpt-4o",
"choices": [{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! How can I help you today?"
},
"finish_reason": "stop"
}],
"usage": {
"prompt_tokens": 12,
"completion_tokens": 9,
"total_tokens": 21
}
}
`
Streaming Response (SSE):
`
POST /v1/chat/completions
{ "stream": true, ... }
Response (text/event-stream):
data: {"id":"abc","choices":[{"delta":{"content":"Hello"}}]}
data: {"id":"abc","choices":[{"delta":{"content":"!"}}]}
data: {"id":"abc","choices":[{"delta":{},"finish_reason":"stop"}]}
data: [DONE]
`
REST vs. gRPC
`
Aspect | REST | gRPC
-------------|-------------------|-------------------
Format | JSON (text) | Protobuf (binary)
Speed | Good | 2-10× faster
Browser | Native support | Needs proxy
Streaming | SSE/WebSocket | Native bidirectional
Tooling | Ubiquitous | Growing
Learning | Easy | Steeper curve
Best For | Public APIs | Internal services
Versioning Strategies
`
Strategy | Example | Pros/Cons
-------------|------------------------|--------------------
URL path | /v1/users, /v2/users | Clear, cacheable
Header | Accept: application/vnd.api+json;v=2 | Clean URLs, harder
Query param | /users?version=2 | Simple, less RESTful
Error Handling
Standard Error Response:
`json`
{
"error": {
"code": "invalid_request_error",
"message": "The 'model' field is required.",
"type": "invalid_request_error",
"param": "model"
}
}
Error Best Practices:
- Use consistent error format across all endpoints.
- Include actionable error messages.
- Log request ID for debugging.
- Don't expose internal details in production.
Pagination
Cursor-Based (preferred for real-time data):
`json
GET /messages?limit=20&after=cursor_abc123
Response:
{
"data": [...],
"has_more": true,
"next_cursor": "cursor_xyz789"
}
`
Offset-Based (simpler, less efficient):
`json
GET /users?limit=20&offset=40
Response:
{
"data": [...],
"total": 1000,
"limit": 20,
"offset": 40
}
`
Rate Limiting
Headers to Include:
`
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1677652288
Retry-After: 60
Best Practices
- Be Consistent: Same patterns across all endpoints.
- Be Predictable: Developers should guess correctly.
- Be Complete: Include all needed info in responses.
- Document Everything: OpenAPI/Swagger specs.
- Version Early: Plan for evolution from day one.
- Test Thoroughly: Automated API contract tests.
API design is the user interface for developers — well-designed APIs make integration easy and enjoyable, while poor APIs create friction that slows adoption and increases support burden, making API design a critical skill for building successful developer products.