Glossary: RequestGlossary

A request, in the context of an API, is a message sent by a client to an API server to perform a specific action or retrieve data.

API requests follow a defined protocol, preferably HTTPS but sometimes HTTP, and consist of the various components listed below that convey the necessary information for the server to process the request and return an appropriate response:

• HTTP method: Specifies the type of action the request is asking the server to perform. Common HTTP methods include:
  • GET: Retrieve a resource or a list of resources from the API.
  • POST: Submit data to the API to create a new resource.
  • PUT: Update an existing resource.
  • DELETE: Remove an existing resource.
• URL (uniform resource locator): The endpoint or address to which the request is sent. It typically includes the server address and the specific resource path, e.g. https://api.example.com/v2/customer.
• Headers: Metadata included as part of the request that provide additional information. Common headers include:
  • Content-Type: Specifies the media type of the request body. For example, the content type of JSON requests is application/json.
  • Authorization: Contains credentials for authenticating the request. In requests made using the OAuth 2 protocol, the value of this header is the string Bearer token followed by the token string.
• Query parameters: Key-value pairs added after the URL to pass additional data. They are typically used to filter or modify the response. For example, the following request asks for a list of only the customers who are active: https://api.example.com/v2/customer?status=active.
• Body: The request’s payload — the data to be sent to the API. This is mainly used with the POST and PUT methods. Here’s an example of a JSON body:

{
  "id"    : "01234",
  "name"  : "Jane Doe",
  "email" : "jane.doe@example.com"
}