Make an API request
Below we introduce the service usage and request methods of the API, and provide examples to illustrate how to call the API.
Request URI
The API we provide conforms to the design theory of REST API.
REST observes the entire network from the perspective of resources, and the resources distributed throughout are determined by URI (Uniform Resource Identifier), while the client’s application obtains resources through URL (Unified Resource Locator).
The general structure of a URL is:
{URI-scheme}://{Endpoint}/{Resource-path}?{Query-param}For example:
https://api-staging.alauda.cn/apis/auth.alauda.io/v1/projects?limit=20The parameter descriptions in the URL are shown in the table below.
| Parameter | Required | Description |
|---|---|---|
| URI-scheme | Yes | The protocol used to transmit the request. All APIs currently use the https protocol. Using the https protocol indicates accessing the resource through the secure SSL-encrypted HTTP protocol. |
| Endpoint | Yes | The domain name or IP address of the server where the resource is stored. Please obtain the domain name or IP address of the actual deployed server. For example: “api-staging.alauda.cn” or “192.144.193.251”. |
| Resource-path | Yes | The resource path, which is also the access path of the API. Obtained from the request line and URI parameters of each interface. For example, the URI of the interface for viewing project details is “apis/auth.alauda.io/v1/projects”. |
| Query-param | No | Query parameters used for filtering and screening when requesting the interface. Whether it is required or not, please refer to the specific interface description. The input format is like “q=value&q1=value1”. Note: The query parameters and the request line need to be separated by ?. |
Request methods
In the HTTP protocol, multiple request methods (also known as operations or actions) can be used to indicate how to access the specified resource.
| Method | Description |
|---|---|
| GET | Requests the server to return the specified resource. |
| POST | Requests the server to add a new resource or perform a special operation. |
| PUT | Requests the server to update the specified resource. |
| DELETE | Requests the server to delete the specified resource, such as a storage volume. |
| PATCH | Requests the server to update partial content of a resource. When the resource does not exist, PATCH may create a new resource. |
In the request line of each API description, you can view the specific request method. For example, the request method for the project list API is GET apis/auth.alauda.io/v1/projects, where GET is the current API’s request method.
Request header
Additional request header fields, such as those required by the specified URI and HTTP method. For example, the request header Content-Type defines the message body type, and the request header may also include authentication information.
| Name | Description | Required |
|---|---|---|
| Content-Type | The MIME type of the entity being sent. It is recommended to use application/json by default. For APIs such as object and image uploads, the media type can be determined according to the different stream types. |
Yes |
| Authorization | Your token. When calling the API, the token is used for authentication. You need to include the token information in the request message header to identify the identity of the user sending the request. |
Yes |
Request body
Refers to the request body in the API description. This part is optional, and APIs with GET and DELETE operation types do not require a message body. The specific content of the message body depends on the specific API.
The request message body is usually sent in a structured format (such as JSON or XML), corresponding to the Content-Type in the request message header, and carries content other than the request message header. If the parameters in the request message body support Chinese characters, the Chinese characters must be encoded in UTF-8.
Coding format
The request content must be encoded using UTF-8, otherwise we will not be able to decode some special characters.