API Design Guidelines

You've now designed a complete User module with schemas, endpoints, components, and authentication. But as your API grows and more team members contribute, maintaining consistency becomes challenging. How do you ensure everyone follows the same naming conventions, path structures, and error handling patterns?

This is where API Design Guidelines come in. Design guidelines are a set of standards and best practices that ensure your API is consistent, professional, and easy to use.

In this article, we'll learn how to create and use API design guidelines in Apidog, and leverage AI features to check compliance and improve naming.

1. Why Do You Need Design Guidelines?

API Design Guidelines are a documented set of rules and conventions for designing APIs. They define how your team should name fields, structure paths, handle errors, and more.

Without Design Guidelines

Inconsistency — Different naming styles (camelCase vs snake_case)

Confusion — Unclear path structures (/user vs /users)

Poor Developer Experience — Unpredictable API behavior

Hard to Maintain — No standard to follow when making changes

Team Conflicts — Different developers follow different patterns

With Design Guidelines

Consistency — All endpoints follow the same patterns

Better Collaboration — Team aligns on standards

Professional Quality — API follows industry best practices

Easier Onboarding — New team members have clear guidelines

OpenAPI Compliance — API specifications are standardized

2. Creating API Design Guidelines in Apidog

Apidog makes it easy to create design guidelines for your project.

Step 1: Create a New Design Guideline

In your Apidog project, click the "+" button above the folder tree

Select "New API design guidelines"

Step 2: Choose a Template

You'll be presented with two options:

Option 1: Example Template (Recommended)

What it is: A complete, ready-to-use design guideline template

Based on: OpenAPI Specification and Microsoft API Design Best Practices

Includes: Comprehensive rules for naming, paths, status codes, errors, and more

Best for: Most teams, especially those starting fresh

Option 2: Blank Template

What it is: A basic structure with minimal content

Best for: Teams with existing design standards who want to customize from scratch

For the User module, choose the "Example Template" to start with industry best practices.

Step 3: Preview and Confirm

Preview the template content

Click "Confirm" to create the guideline

The API design guideline will appear at the top of your folder tree, making it visible to all team members.

3. Understanding the Design Guideline Structure

Apidog's example template covers these key areas:

1. Naming Conventions

Field Naming:

Use camelCase for JSON field names (e.g., firstName, createdAt)

Use descriptive names that clearly indicate the field's purpose

Avoid abbreviations unless widely recognized

Endpoint Naming:

Use lowercase and hyphens for multi-word paths (e.g., /user-preferences)

Or use lowercase with no separators (e.g., /userpreferences)

Be consistent across the API

2. Path Design

RESTful Resource Paths:

Use plural nouns for collections (e.g., /users, not /user)

Use resource hierarchy to show relationships (e.g., /users/{id}/orders)

Keep paths simple and intuitive

Path Parameters:

Use {id} for resource identifiers

Use descriptive names for non-ID parameters (e.g., /users/{userId}/posts/{postId})

3. HTTP Status Codes

Common Status Codes:

200 OK — Successful GET, PUT, PATCH

201 Created — Successful POST (resource created)

204 No Content — Successful DELETE or action with no response body

400 Bad Request — Invalid request parameters

401 Unauthorized — Authentication required or failed

403 Forbidden — Authenticated but not authorized

404 Not Found — Resource doesn't exist

422 Unprocessable Entity — Validation errors

500 Internal Server Error — Server-side error

4. Error Handling

Standard Error Response:

Use consistent error response structure (e.g., RFC 9457 Problem Details)

Include error type, title, status, detail, and instance

Provide helpful error messages for developers

5. Versioning

API Versioning:

Use URL versioning (e.g., /v1/users) or header versioning

Clearly document breaking changes

Support previous versions during deprecation period

4. Why OpenAPI Specification Compliance Matters

The OpenAPI Specification (OAS) is an industry standard for describing RESTful APIs. Following it ensures:

Benefits of OpenAPI Compliance

Interoperability — Your API works with OpenAPI tools (Swagger UI, Postman, etc.)

Documentation — Automatically generate interactive API documentation

Code Generation — Generate client SDKs in multiple languages

Validation — Validate API requests and responses against the spec

Industry Standard — Widely adopted by companies like Microsoft, Google, IBM

Common Compliance Issues

Missing descriptions — Endpoints or parameters without descriptions

Inconsistent naming — Mixed camelCase and snake_case

Missing examples — No request or response examples

Invalid status codes — Using non-standard HTTP status codes

Missing schemas — Inline definitions instead of reusable schemas

5. Customizing Design Guidelines for Your Team

After creating the guideline, you can customize it:

Click on the API Design Guidelines at the top of the folder tree

Edit the content using Apidog's markdown editor

Add or modify sections based on your team's needs

Common customizations:

Add company-specific naming conventions

Define custom error codes

Add security requirements

Include team-specific examples

6. Using AI Features to Improve Your API Design

Apidog offers AI-powered features to help you follow design guidelines automatically.

AI Naming

What it does: Generates standardized field names based on your design guidelines

How to use:

In any endpoint or schema, hover over a field name

Click the AI naming icon (✨)

Enter a description of what the field represents (or use the existing description)

Click "Send"

The AI will generate multiple field name suggestions based on:

Your API design guidelines

Current document context

The field description

Example:

Description: "When the user account was created"

AI suggestions: createdAt, accountCreatedAt, registrationDate

Each suggestion includes an explanation and rating

Select the best option and click "Adopt" to apply it.

Endpoint Compliance Check

What it does: Analyzes your endpoint against design guidelines and provides a compliance score

How to use:

Open any endpoint in your API

Click the "Endpoint compliance check" button in the upper-right corner

The AI will analyze the endpoint and generate a report

The report includes:

Compliance score for different aspects (naming, structure, documentation, etc.)

Detailed explanations of what's wrong

Suggestions for improvement

Example issues detected:

Field name doesn't follow camelCase convention

Missing response examples

HTTP status code not standard

Missing endpoint description

7. Applying Guidelines to the User Module

Let's review the User module against design guidelines.

Check Naming Conventions

Review field names:

✅ firstName, lastName, createdAt — Good camelCase

✅ email, phone, preferences — Clear and descriptive

⚠️ Check if all fields are consistently named

Review endpoint names:

✅ /users — Plural noun for collection

✅ /users/{id} — Clear resource identifier

✅ /user/login, /user/logout — Consistent naming

Check Path Design

Resource paths:

✅ /users for collection

✅ /users/{id} for individual resource

✅ Simple and intuitive hierarchy

Check Status Codes

Verify correct status codes:

✅ POST /users returns 201 Created

✅ GET /users/{id} returns 200 OK

✅ PUT /users/{id} returns 200 OK

✅ DELETE /users/{id} returns 204 No Content

✅ Error responses use 400, 404, 422 appropriately

Check Error Handling

Verify error responses:

✅ Using Error schema component

✅ Following RFC 9457 structure

✅ Consistent error format across endpoints

8. Using AI to Check User Module Compliance

Let's use AI to check one of our User module endpoints:

Step 1: Open an Endpoint

Open POST /users (Create User) endpoint

Step 2: Run Compliance Check

Click "Endpoint compliance check" in the upper-right corner

Wait for AI to analyze the endpoint

Step 3: Review the Report

The AI will provide scores and feedback on:

Naming Compliance — Are field names following guidelines?

Documentation Quality — Are descriptions clear and complete?

Response Structure — Are responses properly defined?

Error Handling — Are error responses standardized?

Examples — Are request/response examples provided?

Step 4: Make Improvements

Based on the AI feedback:

Update field names if needed

Add missing descriptions

Ensure all responses have examples

Fix any compliance issues

9. Best Practices for Design Guidelines

1. Start Early

Create design guidelines before building many endpoints. It's easier to follow guidelines from the start than to refactor later.

2. Keep Guidelines Accessible

Place the design guideline document prominently in your project so all team members can easily reference it.

3. Review Regularly

As your API evolves, update the design guidelines to reflect new patterns and lessons learned.

4. Use AI Features

Leverage AI naming and compliance checks to automate guideline enforcement.

5. Educate Your Team

Ensure all team members understand the guidelines and why they matter.

10. Key Takeaways

API Design Guidelines help you create consistent, professional APIs:

Create Guidelines Early — Use Apidog's example template to start

Follow OpenAPI Specification — Ensures compatibility and interoperability

Cover Key Areas — Naming, paths, status codes, errors, versioning

Customize for Your Team — Add company-specific standards

Use AI Features — AI naming and compliance checks automate enforcement

Check Compliance Regularly — Review endpoints against guidelines

Benefits:

Consistency — All endpoints follow the same patterns

Quality — Professional, standards-compliant APIs

Efficiency — Team works faster with clear guidelines

Maintainability — Easier to update and extend the API

What's Next?

Now that your User module has design guidelines and authentication, you've completed the design phase!

Let's review the key concepts in the Chapter Summary before moving on to development.

API Design Guidelines

1. Why Do You Need Design Guidelines?#

Without Design Guidelines#

With Design Guidelines#

2. Creating API Design Guidelines in Apidog#

Step 1: Create a New Design Guideline#

Step 2: Choose a Template#

Step 3: Preview and Confirm#

3. Understanding the Design Guideline Structure#

1. Naming Conventions#

2. Path Design#

3. HTTP Status Codes#

4. Error Handling#

5. Versioning#

4. Why OpenAPI Specification Compliance Matters#

Benefits of OpenAPI Compliance#

Common Compliance Issues#

5. Customizing Design Guidelines for Your Team#

6. Using AI Features to Improve Your API Design#

AI Naming#

Endpoint Compliance Check#

7. Applying Guidelines to the User Module#

Check Naming Conventions#

Check Path Design#

Check Status Codes#

Check Error Handling#

8. Using AI to Check User Module Compliance#

Step 1: Open an Endpoint#

Step 2: Run Compliance Check#

Step 3: Review the Report#

Step 4: Make Improvements#

9. Best Practices for Design Guidelines#

1. Start Early#

2. Keep Guidelines Accessible#

3. Review Regularly#

4. Use AI Features#

5. Educate Your Team#

10. Key Takeaways#

What's Next?#