Apidog Docs
🇺🇸 English
  • 🇺🇸 English
  • 🇯🇵 日本語
HomeLearning CenterSupport CenterAPI References
HomeLearning CenterSupport CenterAPI References
Discord Community
Slack Community
X / Twitter
🇺🇸 English
  • 🇺🇸 English
  • 🇯🇵 日本語
  1. Design APIs
  • Apidog Learning Center
  • Get started
    • Introduce Apidog
    • Basic concepts in Apidog
    • Navigating Apidog
    • Quick Start
      • Overview
      • Specify a new endpoint
      • Make a request to the endpoint
      • Add an assertion
      • Create a test scenario
      • Share your API documentation
      • Explore more
      • Send a request and save as an endpoint
    • Migration
      • Overview
      • Manual import
      • Scheduled import
      • Import options
      • Export data
      • Import from...
        • Import from Postman
        • Import OpenAPI (Swagger) spec
        • Import cURL
        • Import Markdowns
        • Import from Insomnia
        • Import from apiDoc
        • Import .har file
        • Import WSDL
  • Design APIs
    • Overview
    • Create a new API project
    • Endpoint basics
    • Components
    • Common fields
    • Global parameters
    • Endpoint change history
    • Batch endpoint management
    • Configure multiple request body examples
    • Schemas
      • Generate Schemas from JSON etc.
      • Build a schema
      • Overview
      • Create a new schema
    • Security schemes
      • Overview
      • Create a security scheme
      • Use the security scheme
      • Security scheme in online documentation
    • Advanced features
      • Custom endpoint fields
      • Import endpoints as test steps
      • Endpoint status
      • Appearance of parameter lists
      • Endpoint unique idenfication
  • Develop and Debug APIs
    • Overview
    • Generate requests
    • Send requests
    • Endpoint cases
    • Dynamic values
    • Validate responses
    • Design-first Mode & Request-first Mode
    • Generate code
    • Environments & variables
      • Overview
      • Using variables
      • Environments & services
    • Vault secrets
      • Overview
      • HashiCorp Vault
      • Azure Key Vault
      • AWS Secrets Manager
    • Pre/Post processors
      • Overview
      • Assertion
      • Extract variable
      • Wait
      • Database operations
        • Overview
        • MongoDB
        • Redis
        • Oracle Client
      • Using scripts
        • Overview
        • Postman scripts reference
        • Pre processor scripts
        • Post processor scripts
        • Public scripts
        • Calling other programming languages
        • Using JS libraries
        • Visualizing responses
        • Script examples
          • Assertion scripts
          • Using variables in scripts
          • Using scripts to modify request messages
          • Other examples
    • Dynamic values Modules
  • Mock API data
    • Overview
    • Smart mock
    • Custom mock
    • Mock priority sequence
    • Mock scripts
    • Cloud mock
    • Self-hosted runner mock
    • Mock language (Locales)
  • Automated tests
    • Overview
    • Test reports
    • Test scenarios
      • Create a test scenario
      • Pass data between requests
      • Flow control conditions
      • Import endpoints/endpoint cases from other projects
      • Sync data from endpoints/endpoint cases
      • Export test scenarios
    • Run test scenarios
      • Run a test scenario
      • Data-driven testing
      • Run test scenarios in batch
      • Scheduled tasks
      • Manage the runtime environment of APIs from other projects
    • Test APIs
      • Integration testing
      • Performance testing
      • End-to-end testing
      • Regression testing
    • Apidog CLI
      • Overview
      • Installing and running Apidog CLI
      • Apidog CLI Options
    • CI/CD
      • Overview
      • Integrate with Jenkins
      • Integration with Gitlab
  • Publish API Docs
    • Overview
    • API Technologies Supported
    • Quick share
    • View the API documentation
    • Publish docs sites
    • Folder tree settings
    • Custom layouts
    • Visibility settings
    • Endpoint SEO settings
    • Custom domain
    • Embedding values in document URLs
    • Documentation Search
    • Integrating Google Analytics with Doc Sites
    • CORS Proxy
    • API Versions
      • Overview
      • Create API versions
      • Publish API versions
      • Share endpoints with API versions
  • Send requests
    • Overview
    • gRPC
    • Use request proxy agents for debugging
    • SOAP/WebService
    • GraphQL
    • WebSocket
    • Socket.IO
    • SSE debugging
    • Create requests
      • Request History
      • Request basics
      • Parameters and body
      • Request headers
      • Request settings
      • HTTP/2
    • Authentication and authorization
      • Overview
      • CA and client certificates
      • Authorization types supported by Apidog
      • Digest Auth
      • OAuth 1.0
      • OAuth 2.0
      • Hawk Authentication
      • Kerberos
      • NTLM
      • Akamai EdgeGrid
    • Response and cookies
      • Overview
      • API response in Apidog
      • Create and send cookies
      • Debug requests
      • Save the request as an endpoint
  • Branches
    • Overview
    • Create a new sprint branch
    • Test APIs in a branch
    • Design API in a branch
    • Merge sprint branches
    • Manage sprint branches
  • Apidog MCP Server
    • Overview
    • Conntect API Specification within Apidog Project to AI via Apidog MCP Server
    • Conntect Online API Documentation Published by Apidog to AI via Apidog MCP Server
    • Conntect OpenAPI Files to AI via Apidog MCP Server
  • Best practices
    • How to handle API signatures
    • How to access OAuth 2.0 protected APIs
    • Apidog collaboration workflow
    • Managing authentication state in Apidog
  • Administration
    • Onboarding Checklist
      • Basic Concepts
      • Onboarding Guide
    • Managing Teams
      • Managing Teams
      • Managing Team Members
      • Member Roles & Permission Settings
      • Team Activities
      • Team Resources
        • General Runner
        • Team Variables
        • Request Proxy Agent
      • Real-time Collaborations
        • Team Collaboration
    • Managing Projects
      • Managing Projects
      • Managing Project Members
      • Notification Settings
      • Project Resources
        • Database Connection
    • Managing Organizations
      • Single Sign-On (SSO)
        • SSO Overview
        • Configure Microsoft Entra ID
        • Configure Okta
        • Configure SSO for an Organization
        • Managing user accounts
        • Mapping Groups to Teams
      • SCIM Provisioning
        • Intro to SCIM Provisioning
        • Microsoft Entra ID
        • Okta
      • Organization Resources
        • Self-hosted Runner
  • Billing
    • Overview
    • Credits
    • Unable to use credit cards?
    • Managing subscriptions
    • Upgrade plan
  • Add-ons
    • API Hub
    • Apidog Intellij IDEA plugin
    • Browser Extension
      • Chrome
      • Microsoft Edge
    • Request Proxy
      • Request proxy in Apidog web
      • Request proxy in shared docs
      • Request proxy in Apidog client
  • Account & preferences
    • Language settings
    • Data backup
    • Network proxy configuration
    • Hot keys
    • Updating Apidog
    • Generate OpenAPI access token
    • Deleting account
    • Account settings
  • References
    • API-Design First Approach
    • Apidog OpenAPI/Swagger Specificaiton Extensions
    • JSONPath
    • XPath
    • Regular Expressions
    • JSON Schema
    • CSV File Format
    • Install Java Environment
    • Runner deployment environment
    • Apidog flavored Markdown
  • Apidog Europe
    • Apidog Europe
  • Support Center
  1. Design APIs

Specify an endpoint

In Apidog, designing and setting up an API endpoint is a foundational step in creating robust and effective APIs.
It is recommended to design endpoints in compliance with OpenAPI specifications(OAS) to ensure smooth compatibility with various tools and services within the OpenAPI ecosystem. Deviating from the OAS may lead to compatibility issues when utilizing OpenAPI-compliant tools and services.
To create a new endpoint within the APIs module, click on the New Endpoint button.
A clear and complete endpoint should include the following elements:
1.
Endpoint path
2.
Request method
3.
Endpoint metadata
4.
Request
5.
Response and example
Design-first Mode
Request-first Mode
image.png
Apidog's endpoint interface has two modes: Design-first Mode for API Design-first and Request-first Mode for Code-first approaches. You can switch modes at the bottom-left corner of the interface. Learn more about Design-first Mode/Request-first Mode.

Endpoint path#

The endpoint path serves as a specific address where the API can interact with external applications. This is what the client will use to access the API service.
Unlike Postman, Apidog recommends following the OpenAPI specification. Instead of writing the full URL for each endpoint, you only need to enter the Path (for example, /users). The Base URL should be set in the environment, and Apidog will automatically add it in front of the Path when running the endpoint. This means you don’t need to manually include the domain or use variables in the Path.
Apidog endpoint url.png
To stay consistent with the OpenAPI standard, Apidog also recommends starting all Paths with a /. This keeps your API design clean, organized, and ensures you get the full benefit of Apidog’s features.
Apidog endpoint path.jpg
Why it is recommended to start paths with /
Starting paths with / is recommended to adhere to the OAS. Failing to start paths with / can lead to various compatibility issues when using tools within the OpenAPI ecosystem.
Additionally, using / at the beginning of paths enables the utilization of URL pattern mock functionality essential for testing and validation purposes in Apidog.

Request method#

The request method determines how the client interacts with the server-side resource. Each method carries its own semantics and dictates the server's response. When designing an API, select the most appropriate request method based on business requirements to effectively carry out the intended operation.
The following are commonly used API request methods:
1.
GET: Retrieves specified resources without side effects. It uses query parameters to transmit data.
2.
POST: Submits data for processing and may have side effects. Data is usually sent in the request body.
3.
PUT: Updates or replaces specified resources entirely.
4.
DELETE: Removes specified resources.
5.
OPTIONS: Inquires about the HTTP methods supported by the target resource.
6.
HEAD: Similar to GET, but only retrieves the response headers. This is useful for checking resource existence and modifications without downloading the resource content.
7.
PATCH: Updates partial information of specified resources.
8.
TRACE: Returns the request received by the server. This method is primarily used for debugging and diagnostic purposes.
9.
CONNECT: Establishes a tunnel to the server, typically used for proxy server request forwarding.

Endpoint metadata#

In Apidog, endpoints come with default metadata fields that define and manage the API's documentation, accessibility, and lifecycle.
Here is a concise overview of each default metadata field:
Name
A descriptive name that outlines the endpoint's functionality.
Status
Default status is "Developing". You can modify this under "Endpoint Status" to reflect different stages such as Testing or Production.
Learn more about Endpoint status.
Maintainer
Specifies the Apidog team member responsible for the endpoint. Select a user from your account to assign this role.
Tags
Keywords or phrases that categorize or describe the endpoint. You can type to create new tags or select from existing ones.
Service
The base URL to which the endpoint path is appended. Set by default to "Inherit from parents", but can be manually specified through the environment settings in the interface’s top-right corner.
Learn more about Environments and services.
OperationId
A unique identifier (operationId in OAS) that helps distinguish this operation within the API.
Description
Detailed information about the endpoint's purpose and usage, supporting Markdown for enhanced formatting.
Besides the standard metadata fields provided for an endpoint, you have the flexibility to add custom fields to further enrich the endpoint's metadata.

Request#

Request Parameters#

Request parameters are options that can be passed with the request to control the return of data or to modify the server's response.
Request parameters include Query Parameters, Path Parameters, Header Parameters, and Body Parameters.

Query Parameters#

Query parameters are key-value pairs appended to the end of a URL after a question mark '?', and separated by & as follows: ?id=2&status=available. They are used to filter, sort, or modify the output of an API endpoint.
In Apidog, query parameters are described in a separate section for clarity and organization. However, when sending a request, these query parameters are concatenated with the Endpoint path in the manner described above.

Path Parameters#

Path parameters are part of the endpoint's URL itself and are used to identify a specific resource or entity within the API.
In Apidog, Path parameters are denoted using braces rather than colons. Correct example: /pets/{id}, Incorrect example: /pets/:id.
To add Path parameters, just add {parameter} in the endpoint path, and the parameter will automatically appear in the "Path parameters" region.
Do not confuse {parameter} and {{variable}}
{parameter}: Single curly braces are utilized to represent path parameters in Apidog. Path parameters are placeholders in the URL path that dynamically change to specific values when the API endpoint is accessed.
{{variable}}: Double curly braces are employed in Apidog to include variables within requests. These variables can be substituted with actual values when the request is sent, allowing for dynamic and customizable input in API interactions.
Why it is NOT recommended to use {{variable}} in the path
Using {{variable}} does not adhere to the OAS. Following the OAS enables seamless integration with a variety of tools within the OpenAPI ecosystem.
Using {{variable}} in the path will prevent the usage of URL pattern mock functionality in Apidog.

Header Parameters#

Header parameters provide additional information about the request being made and are typically used for authentication, content type, and other metadata.
Learn more about Header Parameters.

Body Parameters#

Body parameters contain the data to be sent in the body of the request, typically used in POST, PUT, and PATCH requests to create or update a resource. The data is usually sent in JSON or XML format.
Learn more about Body Parameters.

Describe parameters#

Parameters should be described with their name, type (string, integer, boolean, etc.), necessity (required or optional), and any default values or constraints.
When describing parameters, the following key properties are commonly used:
1.
Name: The name property specifies the name of the parameter being described. It is a required field and should accurately represent the parameter being defined.
2.
Type: The type property specifies the data type of the parameter's value. Common type values include string, number, integer, boolean, array, object, and more. This property helps define the format and structure of the parameter's value, allowing API consumers to understand the expected data format when making requests.
3.
Description: The description property provides a brief explanation or documentation regarding the parameter. It helps users understand the purpose and usage of the parameter.
4.
Required: The required property specifies whether the parameter is mandatory for the API request. It is a boolean value (true or false) that indicates whether the parameter must be included in the request.
5.
Advanced settings: The Advanced settings property defines the data type, format, and constraints of the parameter. It allows you to provide detailed information about the expected structure and content of the parameter value.
You can efficiently modify the advanced settings of parameters using the Type Editor. Learn more about the Type Editor.

Schemas#

When the body parameter type is JSON or XML, the data structure needs to be set. The data structure can reference the Schemas.
For detailed information about schema, please refer to Schemas.

Response and Example#

After sending a request to the API, the server returns a response. defining the expected responses and providing illustrative examples are crucial steps that enhance understandability and usability for developers interfacing with your API.
The definition of the returned response mainly includes the following parts:
1.
HTTP status code: determine all potential response statuses your endpoint might return, including standard responses like 200 (OK), 404 (Not Found), or 500 (Server Error).
2.
Data format: Define the format of the response that the API will return for each status code. This could be in JSON, XML, HTML, Raw, Binary or any other suitable format.
3.
Schema: For responses carrying data (mainly 200 status), detail the structure of the response payload. This includes specifying types, nested objects, optional fields, and arrays. Clear definitions help client developers understand what data to expect and how to parse it. Only JSON and XML can configure schemas.
For detailed information about schema, please refer to Schemas.
4.
Example: Providing an example response is essential for illustrating how the API behaves in real-world scenarios. An example should ideally be a sample data set returned by the server when the endpoint is hit with a predefined request. It should reflect the structure, data format, and types as defined by the response's schema.

Add responses#

In general, it is recommended to define at least one successful response and one error response for each endpoint in your API documentation. This practice ensures comprehensive coverage of various potential outcomes, providing developers with a clear understanding of how the API behaves under different scenarios.
Click the + Add button in the upper right corner of the Responses module to add responses.
Typically in API design, while the successful 200 OK responses often differ across various endpoints due to distinct output data needs, the error responses such as 400 Bad Request and 404 Not Found tend to be consistent across different endpoints. Apidog smartly addresses this commonality with its Response Component feature, which allows for the reuse of predefined error responses, making the API documentation process more efficient and the API behavior more consistent.
Learn more about Response components.
If Response Component is not needed, you can opt to Add Blank Response for defining unique responses within individual endpoints.

Add response examples#

Click on "Add Example" to include response examples in Apidog.
A single response can accommodate multiple diverse examples. When adding examples, provide a name for the example and the corresponding response data.

Automatic Example Generation#

By clicking on Generate Automatically, Apidog will generate reasonable response data based on the Response Schema definition.

Preview the endpoint#

After completing the specification of the endpoint, click on "Save" to save your changes. Then, switch to the "API" tab to preview the endpoint you have just configured.
Modified at 2025-04-27 06:52:07
Previous
Create a new API project
Next
Components
Built with