Using Components and Reusability

You've now designed schemas and created endpoints for the User module. But as your API grows, you'll find yourself repeating the same elements across endpoints—error responses, pagination parameters, common headers, and more.

This is where components come in. Components allow you to define reusable elements once and reference them across multiple endpoints, making your API design more consistent, maintainable, and efficient.

In this article, we'll learn how to use Apidog's component features to improve the User module design with reusable error responses and default templates.

1. What Are Components?

Components are reusable building blocks for your API design. Instead of defining the same error response or security scheme in every endpoint, you define it once as a component and reference it wherever needed.

Why Use Components?

Consistency — All endpoints use the same structure for common elements

Efficiency — Define once, use many times (DRY principle)

Maintainability — Update in one place, changes apply everywhere

OpenAPI Compliance — Components align with OpenAPI specification standards

What Can Be Reusable Components?

In Apidog, you can create reusable components for:

Schemas — Data models (already covered in the previous article)

Responses — Common error responses (400, 404, 500, etc.)

Security Schemes — Authentication methods (will be covered in the next article)

2. Creating Response Components

The most common use case for components is error responses. Errors like 400 Bad Request, 404 Not Found, and 500 Internal Server Error typically have the same structure across all endpoints.

Let's create reusable error response components for the User module.

Step 1: Design Error Response Structure

First, let's design what our error responses should look like. A good error response includes:

{
  "type": "https://api.example.com/errors/not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "The requested user with ID 'usr_invalid' was not found",
  "instance": "/users/usr_invalid"
}

This follows RFC 9457 (Problem Details for HTTP APIs), a standard for API error responses.

Step 2: Create Error Schema

Before creating response components, let's create an Error schema:

Go to Schemas → Click ➕ → New Schema

Name it "Error"

Description: "Standard error response following RFC 9457"

Click "Generate from JSON etc." and paste:

{
  "type": "https://api.example.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request contains invalid data",
  "instance": "/users"
}

Refine the schema:

Mark type, title, status as required

detail and instance are optional

Set status type to integer

Add descriptions for each field

Step 3: Create Response Components

Now let's create response components:

In the left sidebar, navigate to Components → Responses

Click "New Response" to create a new response component

Create 400 Bad Request Component:

Name: "Bad Request"

HTTP Status Code: 400

Content Type: application/json

Schema: Select "Error" schema

Add an example:

{
  "type": "https://api.example.com/errors/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid input parameters",
  "instance": "/users"
}

Added in new endpoints by default: Select "Yes" if you want this automatically added to all new endpoints

Create 404 Not Found Component:

Name: "Not Found"

HTTP Status Code: 404

Content Type: application/json

Schema: Select "Error" schema

Add an example:

{
  "type": "https://api.example.com/errors/not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "The requested resource was not found",
  "instance": "/users/usr_invalid"
}

Create 422 Validation Error Component:

Name: "Validation Error"

HTTP Status Code: 422

Content Type: application/json

Schema: Select "Error" schema (or create an extended version with an errors array)

Add an example:

{
  "type": "https://api.example.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "Request validation failed",
  "instance": "/users",
  "errors": [
    {
      "field": "email",
      "message": "Email format is invalid"
    }
  ]
}

Step 4: Reference Components in Endpoints

Now let's add these error responses to our User endpoints:

Open the POST /users endpoint

Go to the Response tab

Click "Add Response" → Select "From Component"

Choose "Bad Request (400)" from the list

Repeat for "Validation Error (422)"

The response components are now referenced in your endpoint. They appear with a component icon and cannot be edited directly in the endpoint.

Benefits:

If you update the component (e.g., add a new field), all endpoints automatically get the update

Consistency across all endpoints is guaranteed

Step 5: Bulk Add Components

Instead of adding components one by one to each endpoint, use bulk operations:

Go to Components → Responses

Select a response component (e.g., "404 Not Found")

Click the "..." menu → "Batch add to endpoints"

Select which endpoints should include this response:

GET /users/{id}

PUT /users/{id}

DELETE /users/{id}

Click "Confirm"

Now the 404 response is added to all selected endpoints at once.

3. Default Response Template

Many organizations have a standardized response structure. For example, all successful responses might follow this pattern:

{
  "success": true,
  "data": { /* actual data here */ },
  "timestamp": "2024-01-15T10:30:00Z"
}

Apidog's Default Response Template lets you set this as the starting point for all new endpoints.

Configure Default Response Template

Go to Components → Default Response Template

Edit the template:

Status Code: 200

Content Type: application/json

Schema: Define your standard wrapper structure

Every new endpoint will now start with this response structure

Important: Changes to the default template only affect new endpoints. Existing endpoints remain unchanged.

4. Component Management Best Practices

Updating Components

When you update a component:

Go to Components → select the component

Make your changes

All endpoints referencing this component are automatically updated

Use case: If you need to add a new field to all error responses (e.g., requestId), update the Error schema once, and it applies everywhere.

Dereferencing Components

Sometimes you need to customize a component for a specific endpoint:

In the endpoint, hover over the referenced component

Click "Dereference"

The component becomes a regular response that you can edit

Changes to the original component will no longer affect this endpoint

When to dereference:

The endpoint needs a slightly different error structure

You want to customize one specific case without affecting others

Versioning Considerations

When your API evolves:

Minor changes (adding optional fields): Update components directly

Breaking changes (removing fields, changing types): Create new components with version suffixes (e.g., ErrorV2)

5. Practical Exercise: Add Components to User Module

Let's apply what we've learned to the User module endpoints:

Task 1: Add Error Response Components

Add 400 Bad Request to all endpoints that accept input:

POST /users

PUT /users/{id}

POST /user/login

Add 404 Not Found to endpoints that fetch specific resources:

GET /users/{id}

PUT /users/{id}

DELETE /users/{id}

Add 422 Validation Error to endpoints with complex validation:

POST /users

PUT /users/{id}

Use bulk operations to save time!

Task 2: Verify Consistency

Check that all your endpoints now have:

Consistent error response structures

All error responses reference the same Error schema

Each error response includes appropriate examples

6. Key Takeaways

Using components and reusability features in Apidog helps you:

Response Components — Define error responses once, reuse everywhere

Bulk Operations — Add components to multiple endpoints at once

Default Template — Set a standard starting response for all new endpoints

Dereferencing — Customize components for specific endpoints when needed

OpenAPI Compliance — Components align with OpenAPI specification standards

Benefits:

Consistency — All endpoints follow the same patterns

Efficiency — Update once, apply everywhere

Maintainability — Easier to manage and evolve your API

Better Documentation — Clear, consistent API documentation

What's Next?

Now that your User module has well-structured endpoints with reusable components, the next step is to secure your API with authentication. In the next article, we'll learn how to set up authentication schemes to protect endpoints that require user login.

Continue with Setting Up Authentication.

Using Components and Reusability

1. What Are Components?#

Why Use Components?#

What Can Be Reusable Components?#

2. Creating Response Components#

Step 1: Design Error Response Structure#

Step 2: Create Error Schema#

Step 3: Create Response Components#

Step 4: Reference Components in Endpoints#

Step 5: Bulk Add Components#

3. Default Response Template#

Configure Default Response Template#

4. Component Management Best Practices#

Updating Components#

Dereferencing Components#

Versioning Considerations#

5. Practical Exercise: Add Components to User Module#

Task 1: Add Error Response Components#

Task 2: Verify Consistency#

6. Key Takeaways#

What's Next?#

1. What Are Components?

Why Use Components?

What Can Be Reusable Components?

2. Creating Response Components

Step 1: Design Error Response Structure

Step 2: Create Error Schema

Step 3: Create Response Components

Step 4: Reference Components in Endpoints

Step 5: Bulk Add Components

3. Default Response Template

Configure Default Response Template

4. Component Management Best Practices

Updating Components

Dereferencing Components

Versioning Considerations

5. Practical Exercise: Add Components to User Module

Task 1: Add Error Response Components

Task 2: Verify Consistency

6. Key Takeaways

What's Next?