Skip to main content

API Design

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 API" 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.

Design an API​

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 API 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 is recommended to not include the HTTP protocol and domain name. This part is recommended to be set in the "Pre-URL" of the debugging environment, and the URL for API debugging will automatically add the "Pre-URL" of the current environment.
  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 "Pre-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): used to obtain specified resources, should not have side effects, and use query parameters to pass parameters.
  2. POST (submit): used to submit data, may have side effects, and can pass request body parameters.
  3. PUT (update): used to update or replace specified resources.
  4. DELETE (delete): used to delete specified resources.
  5. OPTIONS (options): used to 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): used to update part of the information of the specified resource.
  8. TRACE (trace): used to echo the request received by the server, used for debugging and diagnosis.
  9. CONNECT (connect): used to establish a network connection with the server, usually used for request forwarding of proxy servers.

3. Request Parameters​

The request parameters include Query parameters and Path parameters.

Params parameter​

Query parameters are a parameter passing method in API requests. They are usually used to pass some optional parameters, such as filtering conditions, sorting methods, paging parameters, etc. It is not recommended to directly write Query parameters, that is, the parameters after ? in the URL, directly into the API path. 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 temporary 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
  • Data structure: Only JSON and XML can configure data structures. After defining the data structure, the system will automatically verify whether the returned data conforms to the defined data structure during API debugging. For detailed information about data structures, please refer to 《Data Structure》.
  • 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 data structures 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.Through the example, the requester can understand the data structure, data format, data content, etc. returned by the API, so as to better understand how to use the API API.

Public Response​

Common Response is mainly used to implement the reuse of returned responses. Usually, different APIs will return the same data structure under certain circumstances, such as resource not found (404), no access permission (401), etc. It is recommended to set these as common responses to avoid duplicate writing and facilitate unified management.

Setting method: Open Project Settings->Common Response, and manage common responses here.

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.