API Style Guide

In this tutorial, you will learn about API Style Guide. We cover key concepts, practical examples, and best practices to help you master this topic.

An API style guide defines standards for naming conventions, URL formatting, parameter case styles, documentation patterns, error response formats, versioning strategy, and design conventions that ensure consistency across every endpoint and SDK in your API ecosystem.

What You'll Learn

What an API style guide covers, how to define naming and formatting conventions, how to standardize documentation patterns, how to establish error response formats, how to set versioning policies, and how to enforce the style guide with automated linting tools.

Why It Matters

Inconsistent Api Design confuses developers. One endpoint uses camelCase parameters, another uses snake_case. One returns errors as a string, another returns an object. A style guide eliminates these inconsistencies and makes your entire API predictable and easier to integrate.

Real-World Use

The DodaTech API style guide enforces snake_case for request parameters, UpperCamelCase for response object names, bearer token authentication, RFC 9457 error format, and semantic versioning. All new endpoints must pass a Spectral linter that enforces these rules before deployment.

Style Guide Coverage

flowchart TD
  A[API Style Guide] --> B[Naming Conventions]
  A --> C[URL Design]
  A --> D[Parameter Standards]
  A --> E[Response Formats]
  A --> F[Error Standards]
  A --> G[Versioning]
  A --> H[Documentation Patterns]
  B --> I[camelCase vs snake_case]
  B --> J[Resource naming]
  C --> K[Plural nouns]
  C --> L[Hierarchy depth]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Naming Conventions

Define the naming style for every part of the API.

## Naming Conventions

### Resource Names
- Use plural nouns for collection endpoints: `/files`, `/jobs`, `/users`
- Use lowercase with hyphens for multi-word resources: `/rate-limits`, `/compression-profiles`
- Avoid verbs in resource names. Use HTTP methods for actions.

✅ Good: `POST /files/compress`
❌ Bad: `POST /files/doCompress`

### Parameter Names
- **Request parameters:** snake_case (`file_url`, `per_page`, `compression_level`)
- **Response fields:** snake_case (`job_id`, `download_url`, `created_at`)
- **Header names:** Title-Case with hyphens (`X-Request-ID`, `Idempotency-Key`)

### Enum Values
- Use lowercase with underscores: `zip`, `gzip`, `sevenz`
- Never change enum values after release. Add new values instead.

## URL Design

Define URL patterns and hierarchy rules.

```markdown
## URL Design

### Base URL Format

https://api.dodatech.com/{version}/{resource}

### URL Hierarchy
- Maximum 3 levels of nesting: `/v2/files/{fileId}/versions`
- Use path parameters for resource identifiers
- Use query parameters for filtering and pagination

✅ Good URLs:
- `GET /v2/files` — List files
- `GET /v2/files/{fileId}` — Get specific file
- `POST /v2/files/compress` — Compress a file

❌ Bad URLs:
- `GET /v2/getFiles` — Verb in URL
- `POST /v2/file/compress` — Singular resource
- `/v2/files/listFiles?format=zip` — Mixed conventions

## Parameter Standards

Standardize how parameters are documented and validated.

```markdown
## Parameter Standards

### Required Parameters
- Mark every parameter as required or optional
- Use HTTP 400 for missing required parameters
- Never silently default a required parameter

### Default Values
- Document the default value for every optional parameter
- Choose sensible defaults that work for most users
- Default values must never change between minor versions

### Pagination
- Always use cursor-based pagination for list endpoints
- Parameters: `cursor` (string), `limit` (integer, max 100)
- Response: `data` array, `next_cursor` string, `has_more` boolean

## Error Response Standards

Standardize error format across all endpoints.

```markdown
## Error Response Standards

All errors MUST follow RFC 9457 Problem Details format:

```json
{
  "type": "https://docs.dodatech.com/errors/{code}",
  "title": "Short, human-readable title",
  "status": 422,
  "detail": "Specific explanation with values that caused the error",
  "instance": "/v2/files/compress",
  "code": "MACHINE_READABLE_CODE",
  "docs_url": "https://docs.dodatech.com/errors/{code}"
}

Error Code Naming

• Uppercase with underscores
• Resource prefix for related errors: FILE_TOO_LARGE, JOB_NOT_FOUND
• Consistent categories: INVALID_*, MISSING_*, RATE_LIMITED

## Documentation Patterns

Standardize how documentation is written.

```markdown
## Documentation Standards

### Endpoint Documentation Template

Every endpoint documentation MUST include:

1. HTTP method and URL path
2. Plain-language description
3. Authentication requirements with scopes
4. Parameters table (name, type, required, default, description)
5. Request body schema with example
6. Response schema with example
7. Error codes table
8. Code examples in at least 3 languages (cURL, Python, <a href="/programming-languages/javascript/">JavaScript</a>)

### Description Style
- Start with a verb: Lists, Creates, Updates, Deletes
- Explain what the endpoint does, not what it is
- Include any rate limits or size constraints

✅ Good: "Creates a compressed archive from a file URL or upload."
❌ Bad: "This endpoint is for compression."

## Versioning Policy

Define how the API is versioned and how changes are communicated.

```markdown
## Versioning Policy

### Semantic Versioning
- **Major version:** Breaking changes (v1 → v2)
- **Minor version:** Backward-compatible additions (v2.0 → v2.1)
- **Patch version:** Bug fixes (v2.0.0 → v2.0.1)

### Version in URL
- Include major version in the URL: `/v2/files`
- Minor and patch versions are transparent to consumers

### Deprecation Policy
- Announce deprecation at least 90 days before removal
- Add Sunset header to deprecated endpoints
- Publish migration guide with every breaking change
- Maintain parallel versions for at least 3 months

## Automated Enforcement

Use tools to enforce the style guide automatically.

```bash
# Spectral ruleset for API style enforcement
npx @stoplight/spectral lint openapi.yaml

# Example custom rule: check for snake_case parameters
npm install -g @stoplight/spectral

# spectral.yaml
rules:
  snake-case-parameters:
    given: $.paths[*][*].parameters[*]
    then:
      field: name
      function: pattern
      functionOptions:
        match: "^[a-z_][a-z0-9_]*$"

Common Mistakes

1. No Style Guide

Not defining conventions means each endpoint follows a different pattern. Developers must learn each endpoint individually instead of relying on consistent patterns.

2. Inconsistent Error Formats

Some endpoints return errors as strings, others as objects, others with different field names. This forces developers to implement custom error handling per endpoint.

3. Overly Prescriptive Rules

Style guides that are too restrictive prevent innovation and create unnecessary friction. Focus on consistency areas that matter most to developers: naming, errors, pagination, and authentication.

4. No Automated Enforcement

A style guide without automated linting is aspirational. Teams forget rules under pressure. Use Spectral or similar tools to enforce rules in CI.

5. Ignoring Existing Standards

Creating custom conventions when well-established standards already exist. Use RFC 9457 for errors, OpenAPI for specs, and semantic versioning for versions.

6. Style Guide That Never Updates

Publishing a style guide and never reviewing it. Update the guide when you learn better patterns or encounter new edge cases.

7. No Examples

Style guide rules without examples are ambiguous. Every rule should include good and bad examples showing correct and incorrect usage.

Practice Questions

1. What is the purpose of an API style guide?

To ensure consistency across all endpoints, parameters, errors, and documentation. A consistent API is predictable and easier to integrate.

2. What are the key areas an API style guide should cover?

Naming conventions, URL design, parameter standards, error response format, versioning policy, documentation patterns, and pagination design.

3. Why use snake_case for parameters and UpperCamelCase for response objects?

Consistency across the API. Choose one convention based on your primary language ecosystem. Python APIs use snake_case. JavaScript APIs use camelCase.

4. How does automated enforcement help maintain style guide Compliance?

Automated linting in CI catches style violations before endpoints are deployed. This ensures consistent API design without requiring manual code reviews for every endpoint.

5. Challenge: Write a one-page API style guide for a fictional API. Include naming conventions, URL design rules, error format specification, documentation template, versioning policy, and two automated linting rules.

FAQ

Mini Project: Create an API Style Guide

Write a complete API style guide for a fictional API. Cover naming conventions, URL design (with 5 good and 5 bad URL examples), parameter standards, error response format with RFC 9457, versioning policy with deprecation rules, documentation template, and 3 automated linting rules with Spectral.

What's Next

Style guides ensure consistency. Now explore the tools that automate API documentation with API Documentation Tools. Then apply everything in the API Documentation Project.