HTTP and REST Fundamentals: Request, Response, and DesignLesson 2.5

Designing for Consistency: API Style Guides and Standards

API style guide, naming conventions, camelCase vs snake_case, date formats, ISO 8601, boolean naming, pagination standards, error codes

Designing for Consistency: API Style Guides and Standards

A consistent REST API feels like it was designed by one person with a clear vision. In reality, most APIs are built by teams over months or years. An API style guide ensures that every endpoint, field name, error code, and response shape follows the same conventions, reducing the cognitive load on API consumers and maintainers alike.

DiagramAPI Naming and Standards Quick Reference

IMAGE PROMPT (replace this block with your generated image):

Flat reference sheet infographic on white background. Title: API Consistency Standards. Six sections in a clean grid. Section 1 — Field Naming: show camelCase (firstName) as recommended (green check), snake_case (first_name) as acceptable (neutral), PascalCase (FirstName) as avoid (red X). Section 2 — Date Format: show ISO 8601 (2024-01-15T10:30:00Z) as correct with green check, Unix timestamp (1705316200) as avoid with red X. Section 3 — Boolean Naming: show isActive, hasVerifiedEmail, isPremium as correct (green). Show active, status as avoid (red). Section 4 — Error Codes: show VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED (SCREAMING_SNAKE_CASE in #3A5EFF). Section 5 — ID Format: show UUID (550e8400-e29b...) and prefixed ID (cus_abc123) as options. Section 6 — URL Casing: show /blog-posts (kebab-case) as correct, /blogPosts and /Blog_Posts as wrong. Each section has a #3A5EFF left border accent. White background, clean layout.

Field Naming Conventions

Choose one naming convention and apply it everywhere. JSON APIs most commonly use camelCase (firstName, lastName, createdAt) because it matches JavaScript conventions. Some APIs use snake_case (first_name, last_name, created_at) for consistency with database column names. Never mix conventions within the same API.

Date and Time Formatting

Always use ISO 8601 format for dates and times: "createdAt": "2024-01-15T10:30:00Z". The Z suffix indicates UTC. This format is unambiguous, sortable, and parseable by every modern programming language. Never return Unix timestamps as your primary date format and never use locale-specific formats like MM/DD/YYYY.

Boolean Field Naming

Boolean fields should be named as questions or states that are clearly true or false: isActive, hasVerifiedEmail, isPremium. Avoid ambiguous names like status or active that could be mistaken for a string or verb.

Error Code Standards

Define a consistent error code taxonomy for your API: VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, FORBIDDEN, RATE_LIMIT_EXCEEDED, INTERNAL_ERROR. Use SCREAMING_SNAKE_CASE for error codes — they are constants, not sentences. Document every error code and what it means.

Pagination Standards

Standardize your pagination approach across all collection endpoints. Cursor-based pagination is best for large datasets: ?after=cursor_abc&limit=20. Page-based pagination is simpler: ?page=3&limit=20. Always include total count, current page, and navigation links in the response metadata.

Ready to practice?

MCQs · Mini project