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

:::tip[]
Apidog's endpoint interface has two modes: DESIGN for API Design-first and DEBUG for Code-first approaches. You can switch modes at the bottom-left corner of the interface. This document is based on the DESIGN mode for API design. Learn more about DESIGN/DEBUG 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.

The endpoint path should have a clear hierarchical structure, which can clearly express the relationship between resources. In the design process, the scalability and ease of understanding of the API should also be considered.

The endpoint path part starting with a slash / in the path box, such as /pets, /pets/{id}.

Endpoint path should NOT include Query parameters (parameters following the ? in a URL). Instead, these should be specified in the Request Parameters section below.

:::tip[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.

:::highlight purple
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.
  :::highlight purple
  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.

:::highlight purple
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.

:::tip[]
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.

:::tip[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.

:::

:::tip[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.

:::highlight purple
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.

:::highlight purple
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.

:::highlight purple
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.

:::highlight purple
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.

:::highlight purple
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.

:::highlight purple
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.