Designing Endpoints

Now that you have your schemas designed and your project structure organized, it's time to create the actual endpoints. Endpoints are the entry points to your API—they define how clients interact with your resources.

In this chapter, we'll learn how to design and create endpoints in Apidog, focusing on how to configure requests and responses with schemas and examples. We'll use the endpoint plan we created earlier and implement the User module endpoints.

1. What Is an Endpoint?

An endpoint is a specific URL path combined with an HTTP method that defines a single operation in your API. For example:

POST /users — Create a new user

GET /users/{id} — Get a specific user

PUT /users/{id} — Update a user

DELETE /users/{id} — Delete a user

Each endpoint consists of:

HTTP Method — What action to perform (GET, POST, PUT, DELETE)

Path — Where the resource is located (e.g., /users/{id})

Request — Parameters, headers, body (if needed)

Response — What the API returns (status codes, data structure, examples)

2. Creating POST /users Endpoint (Create User)

Let's start by creating the POST /users endpoint to create a new user. This endpoint demonstrates how to configure request bodies with schemas and responses.

Step 1: Create the Endpoint

In your Apidog project, navigate to the APIs section → your module

Click "New Endpoint" (or ➕ → New Endpoint)

Set method: Select POST

Set path: /users

Important: Always start paths with / to comply with OpenAPI specification

Don't include the base URL (set in environments)

Add metadata:

Name: "Create User"

Description: "Create a new user account in the system"

Tags: "User"

Status: "Developing" (default)

Step 2: Configure Request Body with Schema

Since this is a POST request, we need a request body:

Go to the Request tab → Body

Select content type: JSON

Click "Schema" and select "User" from your schemas

Apidog will automatically load the User schema structure.

Step 3: Customize Fields for Create Request

The User schema includes all fields, but for the create user endpoint, we need to adjust:

Fields to hide (not needed in request):

id — Generated by system, not provided by client

createdAt — Set by system, not provided by client

Fields to add (needed in request but not in base schema):

password — Required for account creation

In Apidog:

Hide fields:

Hover on a field in the schema (e.g., id or createdAt)

Click "Hide"

Hidden fields won't appear in the request body

Add fields:

Click "Add Field" or use field association

Add password field:

Type: string

Required: ✅

Write-only: ✅ (important for security)

Min length: 8

Description: "User password"

Adjust required/optional:

For create endpoint: email, firstName, lastName, password are required

phone and preferences are optional

Toggle "Required" for each field as needed

Step 4: Generate Request Body Examples

Apidog can automatically generate request body examples based on your schema:

Click "Add" in the request example section

In the popup, click "Auto-generate"

Apidog will automatically create example data that:

Matches your schema structure

Includes all visible fields

Uses appropriate data types and formats

Follows validation rules (patterns, formats, etc.)

Generated example:

{
  "email": "jane.smith@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "password": "securePassword123",
  "phone": "+14155551234",
  "preferences": {
    "newsletter": true,
    "notifications": false
  }
}

Customize the generated example:

Edit values directly in the JSON editor

Modify to show different scenarios (e.g., minimal fields, edge cases)

Add multiple examples by clicking "Add Example" and generating again

Benefits of auto-generated examples:

Saves time — no need to write JSON manually

Always matches your schema — ensures consistency

Easy to customize — generate first, then edit as needed

Step 5: Configure Response

Now let's configure what the API returns:

Go to the Response tab

Click "Add Response" (or "Add Blank Response")

Select status code: 201 (Created)

Set content type: application/json

Click "Schema" and select "User" schema

The User schema will be used, and Apidog automatically excludes write-only fields (like password) from responses.

Step 6: Generate Response Examples

Click "Add Example" in the response section

Click "Auto-generate"

Apidog will create example data that:

Matches your schema structure

Uses appropriate data types

Follows validation rules (patterns, formats, etc.)

Respects field constraints (read-only, write-only)

Automatically excludes write-only fields (like password)

Generated example:

{
  "id": "usr_3Oy2JIS7TMJgEXfM",
  "email": "jane.smith@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "phone": "+14155551234",
  "preferences": {
    "newsletter": true,
    "notifications": false
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

Notice that password is automatically excluded (write-only field).

Add multiple response examples:

Click "Add Example" again

Click "Auto-generate" for each new example

Edit the generated JSON to show different scenarios (e.g., user with minimal data)

Step 7: Add Error Responses

Every endpoint should define error responses:

Click "Add Response"

Add common error responses:

400 Bad Request — Invalid input

422 Unprocessable Entity — Validation errors

For error responses, you can use a shared Error Response Component (we'll cover this in the next chapter) or define inline with schema and examples.

3. Creating GET /users/{id} Endpoint (Get User)

Now let's create the GET /users/{id} endpoint to retrieve a user by ID. This endpoint demonstrates how to configure path parameters and responses.

Step 1: Create the Endpoint

Click "New Endpoint"

Set method: Select GET

Set path: /users/{id}

The {id} is a path parameter (use braces {}, not colons :)

Important: Always start paths with /

Add metadata:

Name: "Get User"

Description: "Retrieve user information by user ID"

Tags: "User"

When you write /users/{id} in the path, Apidog automatically recognizes {id} as a path parameter. You don't need to add it manually.

Note:

In Apidog, use {parameter} syntax in paths, not :parameter

Path parameters are automatically detected—just write them in the path, then configure their properties

Step 2: Configure Response

Go to the Response tab

Click "Add Response"

Select status code: 200 (OK)

Set content type: application/json

Click "Schema" and select "User" schema

Step 3: Generate Response Examples

Click "Add Example"

Click "Auto-generate"

Apidog will generate a response example matching the User schema (excluding write-only fields like password).

Add multiple examples:

Generate additional examples to show different scenarios

Edit to show users with or without optional fields

Step 4: Add Error Responses

Add common error responses:

404 Not Found — User not found

400 Bad Request — Invalid user ID format

4. Apidog Features for Request/Response Configuration

Apidog provides several powerful features for working with requests and responses:

Field Visibility and Association

Hide fields in requests:

System-generated fields (id, createdAt) shouldn't appear in create requests

Hover on a field and click "Hide" to hide it in requests

Hidden fields won't appear in request body or examples

Add fields via association:

Add fields that are only needed in specific endpoints (like password in create/login)

Fields are associated with the endpoint, not the base schema

Useful for endpoint-specific requirements

Adjust required/optional per endpoint:

Base schema defines defaults

Each endpoint can override required/optional settings

Useful for partial updates (PUT endpoints where all fields are optional)

Automatic Example Generation

Apidog's Auto-generate feature creates examples automatically:

Request body/Response examples:

Click "Add Example" → "Auto-generate" to create example from response schema

Excludes write-only fields automatically

Creates realistic sample data matching schema constraints

Can generate multiple examples and customize each

Benefits:

Fast — Generate examples in seconds

Accurate — Always matches your schema

Flexible — Edit generated examples to show different use cases

Schema References

Reference existing schemas instead of duplicating

Changes to schema automatically reflect in all endpoints

Maintains consistency across your API

Multiple Examples

Add multiple examples for different scenarios

Name examples for clarity

Switch between examples when testing

5. Quick Reference: Other Endpoints

For the remaining endpoints, follow similar patterns:

PUT /users/{id} (Update user):

Path parameter: {id} (same as GET)

Request body: User schema with all fields optional (partial update)

Hide: id, createdAt

Don't include: password (use separate endpoint)

Response: 200 with User schema

DELETE /users/{id} (Delete user):

Path parameter: {id}

No request body

Response: 204 No Content (no body)

POST /user/login (Login):

Request body: Simple schema with username and password

Response: 200 with token and expiresAt

POST /user/logout (Logout):

No request body (or optional body)

Response: 200 with success message

6. Organizing Endpoints

After creating endpoints, organize them:

Create folders under Endpoints:

User Management/ — POST, GET, PUT, DELETE /users

Authentication/ — Login and logout

Drag endpoints into appropriate folders

7. Key Takeaways

Designing endpoints involves careful configuration of requests and responses:

Use schemas for request and response bodies to maintain consistency

Customize schemas per endpoint using field visibility and associations

Hide system-generated fields in requests (id, createdAt)

Add endpoint-specific fields via field association (like password)

Generate examples automatically from schemas, then customize

Add multiple examples to show different scenarios

Define error responses for comprehensive API documentation

Use schema references to avoid duplication and maintain consistency

Now that you have endpoints with well-configured requests and responses, you can enhance them with reusable components. In the next chapter, we'll learn about using components and reusability to make your API design more efficient.

Let's continue with Using Components and Reusability.

1. What Is an Endpoint?#

2. Creating POST /users Endpoint (Create User)#

Step 1: Create the Endpoint#

Step 2: Configure Request Body with Schema#

Step 3: Customize Fields for Create Request#

Step 4: Generate Request Body Examples#

Step 5: Configure Response#

Step 6: Generate Response Examples#

Step 7: Add Error Responses#

3. Creating GET /users/{id} Endpoint (Get User)#

Step 1: Create the Endpoint#

Step 2: Configure Response#

Step 3: Generate Response Examples#

Step 4: Add Error Responses#

4. Apidog Features for Request/Response Configuration#

Field Visibility and Association#

Automatic Example Generation#

Schema References#

Multiple Examples#

5. Quick Reference: Other Endpoints#

6. Organizing Endpoints#

7. Key Takeaways#

1. What Is an Endpoint?

2. Creating POST /users Endpoint (Create User)

Step 1: Create the Endpoint

Step 2: Configure Request Body with Schema

Step 3: Customize Fields for Create Request

Step 4: Generate Request Body Examples

Step 5: Configure Response

Step 6: Generate Response Examples

Step 7: Add Error Responses

3. Creating GET /users/{id} Endpoint (Get User)

Step 1: Create the Endpoint

Step 2: Configure Response

Step 3: Generate Response Examples

Step 4: Add Error Responses

4. Apidog Features for Request/Response Configuration

Field Visibility and Association

Automatic Example Generation

Schema References

Multiple Examples

5. Quick Reference: Other Endpoints

6. Organizing Endpoints

7. Key Takeaways