Skip to main content

Introduction

This article introduces you how to design an API in Apidog.

The commonly used API type is HTTP API, and Apidog also uses HTTP API as the main design object. The HTTP API refers to an application program API that communicates based on the HTTP protocol. It is a standard, general-purpose protocol for transferring various types of data.

It is commonly used as a way for web applications, mobile applications, and other client programs to exchange data with a server. Through the HTTP API, client programs can communicate with the server and request or submit data. After receiving the request, the server returns the response data based on the HTTP protocol. Almost all web applications and mobile applications need to exchange data with backend servers through HTTP API.

How to Create an API​

After entering the Apidog project, you can create an HTTP type API by manually creating or importing an external API.

Create Manually​

In the new window, click the "New Endpoint" option, and the system will automatically create an HTTP type API.

Import External API​

Click the "+" button next to the search box on the left, and click the "Import" button. Upload a file or paste the API URL in the import window.

Importing cURL​

Click the + button next to the search box on the left and select the "Import cURL" option. Paste the cURL command into the pop-up window to create a new API endpoint.

Apidog Import cURL

Alternatively, you can paste the cURL command directly into the address bar to create a new API endpoint.

cURL Paste into Address Bar

Design an Endpoint​

A clear and complete API document should have the following elements:

  1. Set the API path
  2. Specify the request method
  3. API request parameter details
  4. Provide return examples
  5. Generate online documents

1. Set the Endpoint Path​

The API path refers to the URL address used to identify the API resource. The requesting party can initiate a request to the server through the API path and obtain a server response. The API 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 API path part starting with a slash / in the API path box, such as /pets, /pets/{id}.

Note
  1. API Path It is recommended not to fill in the HTTP protocol and domain name, but to place this information in the "Base URL" under Environment Management. When starting to send a request, the actual API request address will automatically complement the domain name in the "Base URL".
  2. If there are special circumstances that require the API path to include the HTTP protocol and domain name, the system can also support it, but it is not recommended to do so. When debugging the API, if the system detects that the API path starts with http:// or https://, it will automatically ignore the "Base URL" in the current environment.
  3. The Path parameter in Apidog is represented by braces, not a colon. Correct example: /pets/{id}, wrong example: /pets/:id.
  4. API path cannot contain Query parameters (parameters after ? in the URL), and Query parameters should be filled in the Request Parameters section below.

2. Specify the Request Method​

After specifying the API path, you need to define the request method of the API. The request method specifies the method used by the client to operate on the server-side resource. Each request method has specific semantics and corresponds to the response implemented on the server side. When designing the API, you need to choose the most suitable request method according to business needs to achieve the desired operation.

You can specify the request method on the API document page.

The following are commonly used API request methods:

  1. GET (get): Obtain specified resources, should not have side effects, and use query parameters to pass parameters.
  2. POST (submit): Submit data, may have side effects, and can pass request body parameters.
  3. PUT (update): Update or replace specified resources.
  4. DELETE (delete): Delete specified resources.
  5. OPTIONS (options): Obtain the request methods supported by the target resource.
  6. HEAD (request header): Similar to GET, but only returns the response header, used to check whether the resource exists and whether it is modified.
  7. PATCH (patch): Update part of the information of the specified resource.
  8. TRACE (trace): Echo the request received by the server, used for debugging and diagnosis.
  9. CONNECT (connect): Establish a network connection with the server, usually used for request forwarding of proxy servers.

3. Request Parameters​

The request parameters include Query parameters, Path parameters and Body parameters.

Query Parameter​

A query parameter is a component of a URL that follows a question mark '?' and is used to pass specific information to a web server. You can directly fill in the Query parameters in the "Request Parameters" text box below.

Path Parameters​

Path parameters, also known as "path variables" are a way of passing parameters in an API request. They make the request path more specific, accurately describing the resource the API is operating on. They are usually enclosed in curly braces and serve as placeholders for parameters in the API path. For example, {id} in /pets/{id} represents the path parameter named id. With no additional parameters, the requesting party can determine the API target by simply viewing the specified pet ID in the API path.

Body Parameters​

When an HTTP request is made, parameters are usually required to be sent to the server for processing. These parameters can be passed to the server through the HTTP request header or HTTP request body. Among them, parameters passed through the HTTP request body are called body parameters. Body parameters are included in the request body and are usually form data, JSON data, or binary data.

Parameter Types​

  • none: No body parameters.
  • form-data: Form data. After the user fills in the form information on the front-end API, they send a request to the server via POST or PUT methods. Form data is usually encoded as application/x-www-form-urlencoded or multipart/form-data format and passed to the server as a body parameter.
  • x-www-form-urlencoded: This encoding method is usually used to encode form data and transmit it to the server as a body parameter. Under this encoding method, form data is encoded as a series of key-value pairs, each separated by an &, and the key and value are separated by an =. The Content-Type is application/x-www-form-urlencoded.
  • json: When sending a request to the server through Ajax technology on the front-end API, data can be encoded as JSON format and passed to the server as a body parameter. The server usually uses relevant libraries to parse this data. The Content-Type is application/json.
  • xml: A markup language used to represent data. It can be used not only to represent media types such as text and images, but also to represent structured data. The Content-Type is application/xml.
  • binary: Binary data. When uploading binary data such as files or images, this data can be passed to the server as a body parameter, and the type of this data is usually specified in the request header.
  • raw: This is a data type for sending raw data in the HTTP request body. When using the RAW parameter, the user can directly specify the data to be sent in the request body without using a specific encoding method or format. This method is more flexible and can be used to send various types of data, including plain text, JSON, XML, etc.
Note
  • When the body parameter type is json or xml, the data structure needs to be set. The data structure can reference the data model. For more information, please refer to the document: Data Structure.

When sending a request, the system will automatically add the corresponding Content-Type to the request header according to the Body Parameter Type, so there is no need to set it manually. If you need to manually set the Content-Type in the Header, its value must match the Body Parameter Type, otherwise the system will automatically ignore the manually set Content-Type.

  1. Example: If the Body Parameter Type is form-data, setting the value of Content-Type manually to multipart/form-data; charset=GBK is valid; but if the value is set to application/json, it will be ignored by the system because it does not match the parameter type.
  2. When the Body Parameter Type is raw, there is no restriction on manually setting the value of Content-Type.

Using Environment Variables in Parameters​

Environment variables include global variables and current variables. All parameters can use variables, which are enclosed in double curly braces, such as {{my_variable}}, which refers to the variable named my_variable.

When using variables in parameter values, the values can contain strings other than variables, such as setting the parameter value to prefix-{{my_variable}}-surfix. Assuming the value of the runtime variable my_variable is 123, the actual value of the parameter in the request is prefix-123-surfix.

For more information about variables, please refer to the document: Environment Variables.

4. Provide Response​

After sending a request to the API, the server returns a response. The definition of the returned response mainly includes the following parts:

  • HTTP status code returned by the API
  • Data format of the returned content: JSON, XML, HTML, Raw, Binary
  • Schemas: Only JSON and XML can configure schemas. After defining the schema, the system will automatically verify whether the returned data conforms to the defined data structure during API debugging. For detailed information about schemas, please refer to 《Schemas.
  • Mock data: The system will automatically mock out rich and credible simulation data based on the defined data structure. For detailed information, please refer to 《Mock Function》.

If an API returns different schemas under different circumstances, multiple returned responses can be set. Click the + button in the upper right corner of the returned response module to add.

Success/Failure Example​

It is recommended to set at least two examples: success example and failure example,to better understand data structure,format and content for better use of the API. Click + Add button on the top right corner of the Responses module to add multiple response examples.

By reading examples, requesters can understand the data schemas, data format, and data content returned by the endpoint, so as to better understand how to use the endpoint.

Response Component​

The response component is primarily targeted at endpoint documentation design scenarios.

Typically, a response example for an endpoint is divided into two types: successful examples and failure examples. Common failure responses include "Resource Not Found (404)" and "Unauthorized Access (401)". Although the status codes in failure examples can vary, the structure of the returned response data is usually consistent.

Therefore, it can be extracted as a common response component and managed uniformly for easier reference in other endpoint documentation. For detailed instructions, please refer to Component Library.

5. Generate Online Documentation​

After the API design is completed, it can be easily published as online documentation. Presenting it in the form of online documentation can not only make it easier for team members to consult each other, but also help requesters intuitively understand the usage of different APIs. The online documentation page provides online debugging function, which can directly debug the API on the page.

Click the "Online Share" option in the left menu bar, and click the "Publish" button to complete the online documentation publishing.

Example page: Walk through Apidog.