Making an API Request
This section describes how a REST API is formed and uses the IAM API for obtaining a user tokenas an example to describe how to call an API. A token authenticates the calling of other APIs.
Public cloud APIs comply with RESTful API design rules. REST-based web services are organized into resources. Each resource is identified by one or more URIs. An application accesses a resource based on the resource's URL. A URL is usually in the format of https://Endpoint/uri, in which uri indicates the resource path, that is, the API access path.
Public cloud APIs use HTTPS as the transmission protocol. Requests/Responses are transmitted by using JSON packets, with media type represented by Application/json.
In REST, specific information or data on a network is represented by resources. RESTful APIs allow users to access service resources by creating, querying, updating, and deleting resources.
A REST API request/response pair is divided into the following parts:
Request URI
A request URI is in the following format:
{URI-scheme} :// {Endpoint} / {resource-path} ? {query-string}
Although a request URI is a part of a request header, most programming languages or frameworks require the request URI to be separately transmitted, rather than being conveyed in a request message.
| Parameter | Description |
|---|---|
| URI-scheme | Protocol used for transmitting requests. |
| Endpoint | Domain name or IP address of the server that provides the REST service endpoint. |
| resource-path | Access path of an API for performing a specified operation. Obtain this value from the URI of the API, for example, v3/auth/tokens. |
| Query string | This parameter is optional. For example, you can set it to API version or resource selection criteria. |
Request Method
| Method | Description |
|---|---|
| GET | Requests a server to return specified resources. |
| PUT | Requests a server to update specified resources. |
| POST | Requests the server to add a resource or perform special operations. |
| DELETE | Requests a server to delete specified resources, for example, an object. |
| HEAD | Requests a server resource header. |
| PATCH | Requests a server to update partial content of a specified resource. If the resource does not exist, a new resource will be created. |
Request Headers
You can also add additional fields to the request header, for example, the fields required by a specified URI and an HTTP method. For details about common request headers, see Common Request Parameters. For details about request authentication information, see Token-based Authentication.
Request Body
A request body conveys information other than the request header and is generally sent in a structured format (for example, JSON or XML) defined by the request header field Content-type.
Initiating Requests
You can initiate a request based on the constructed request message in one of the following ways:
- cURL
cURL is a command-line tool used to perform URL operations and transmit information. It serves as an HTTP client that can send HTTP requests to the server and receive response messages. cURL is applicable to API debugging. For more information about cURL, visit https://curl.haxx.se/.
For security purposes, run the curl command on the server to query information, and then clear operation records, including but not limited to records in the ~/.bash_history and /var/log/messages directories (if any).
- Code
You can call APIs using code to assemble, send, and process request messages.
- REST client
Both Mozilla Firefox and Google Chrome provide a graphical browser plug-in, REST client, to send and process requests. For Mozilla Firefox, see Firefox REST Client. For Google Chrome, see Chrome REST Client.
Last Article: Calling APIs
Next Article: Authentication
Did this article solve your problem?
Thank you for your score！Your feedback would help us improve the website.