In HTTP-based web communication, an API request is a message that client software sends to a server-side API endpoint to retrieve information, submit data or request an action. API stands for Application Programming Interface: a software interface through which programs interact. APIs generally need not use HTTP or communicate with a remote server.
The request is the message; the endpoint is the server-side target addressed by a URL. Having that address does not guarantee access. The server combines the received target information with its configuration and connection context to identify the target URI, interprets the method, processes the operation if allowed, and returns a response describing the result.
Main Parts of an API Request
The endpoint URL identifies the destination through its scheme, such as https, and authority, which contains the host and any applicable port. The path identifies the target within that server, together with an optional query after a question mark. Queries commonly use key=value parameters, whose names and meanings are defined by the API.
Headers are name-value fields that provide context, describe content or modify how the request is handled. For example, Content-Type identifies the content format, while Authorization can carry authentication information. These fields are used when applicable, not necessarily in every request.
The body of an API request carries data when appropriate to the operation, such as submitted information or a desired new state. Not every request needs a body. JSON is one structured data format, not an HTTP requirement; an operation specifies the formats it accepts.
API request components
| Feature | Purpose |
|---|---|
| HTTP method | PurposeSpecifies the requested operation; examples include GET, POST, PUT and DELETE. |
| API endpoint | PurposeURL addressing the server-side target; the address does not guarantee access. |
| Request headers | PurposeName-value fields providing context or metadata, such as content format or authentication information. |
| Request body | PurposeCarries data when appropriate to the operation; neither a body nor JSON is required in every request. |
| Query parameters | PurposeOptional inputs in the URL query, commonly key=value pairs with API-defined meanings. |
Common HTTP Methods
Endpoints support different methods; these four are representative rather than exhaustive:
- GET: The client requests a current representation—data describing the target’s state.
- POST: The client submits data for target-specific processing. The server applies the target’s processing rules and reports the result, which may involve creating something or triggering another action.
- PUT: The client requests creation or replacement of the identified target’s state using the supplied data. If successful, the server creates or replaces that state and reports the outcome.
- DELETE: The client requests removal of the association between the target URI and its current functionality. If applied, the server removes that association and reports the outcome; this does not guarantee physical erasure of stored data.
Looking for liquidity, exploring on-ramp/off-ramp services, or seeking expert guidance?
Get startedReading the Response
The server reports its result in an HTTP response with a three-digit status code, relevant headers and possibly a body. Interpret these together with the original method: the content may be retrieved data or an action result, or may explain an error. A 204 (No Content) response reports success without a body.
The first digit identifies a status class. An informational 1xx response can precede the final response. The 2xx class indicates success, but 202 (Accepted) reports acceptance before processing is complete. The other final-response classes are 3xx for redirection or further action, 4xx for client-error conditions, and 5xx for server-error conditions.
In a hypothetical catalogue API, the client sends a GET API request to https://api.example.com/products?category=books with no body. Here, https is the scheme, api.example.com is the host, /products is the path, and category=books is a query parameter that this API defines as a category filter. A 200 (OK) response with Content-Type: application/json and a list of books would mean that retrieval succeeded and the returned data is JSON.
Credentials and HTTPS
An API request needs credentials only when the API or operation requires them; anonymous access is also possible. An API key is a value supplied for access checks, while an access token represents granted access authorization. Required credential types and placement depend on the API, and valid credentials do not guarantee permission.
HTTPS has a different role: it uses TLS, a protocol that secures the connection, to authenticate the server and protect messages against disclosure or alteration in transit. Adding a key or token does not itself encrypt a request or replace HTTPS protection.