HTTP Request Headers and Query Parameters

The Identity Problem

When your client sends a request to a vendor's API, the vendor needs a way to know who is making the call. Without identification, the vendor cannot distinguish one user from another. That makes it impossible to track which account is consuming the service or to enforce usage policies for that account.

Request Path to Account

An API key travels as part of the request sent by your client. The source identifies request headers, query parameters, and the request body as places where a vendor may extract the key. This article focuses on the first two locations: headers and query parameters.

The vendor's server receives the request and extracts the API key. It then looks up the key in its database of valid keys. If the key is found and is valid, the server retrieves the associated user account. The request is now connected to an identified account rather than being an unattributed call.

Headers and Query Parameters

The important idea is not that the key is a separate request. The key travels with the request, and the vendor extracts it from the location expected by that API. Whether the key is placed in a header or a query parameter, the vendor uses it to look up the associated account and validate the request.

Validation and Usage Tracking

After identifying the account, the vendor can process the request with knowledge of who is using the service. After processing, the vendor increments the usage counter so that the request becomes part of the account's usage record.

The counter gives the vendor a record of how much the identified account has used the service. Vendors use this information to enforce rate limits, monitor overall usage, track usage for billing, and identify when an account may be approaching a billing threshold.

Multiple Keys and Service Tiers

Service tiers are another reason the key matters. A vendor might offer a free tier with limited requests per day and a premium tier with higher limits. The API key lets the vendor determine which account and tier are connected to the request, then apply the relevant usage policies.

Common Misunderstandings

• Assuming the vendor can track usage without identifying the caller.

  Without identification, the vendor cannot connect the request to a user account or distinguish one user's consumption from another's.

  Fix: Include the API key with the request in the location specified by the vendor, such as a request header or query parameter.

• Treating all API keys owned by one user as one independently tracked key.

  A single user can own multiple API keys, and each key is tracked independently.

  Fix: Use the independent key records to understand which application is consuming resources.

• Ignoring rate limits and service tiers after obtaining a valid key.

  Vendors use API keys to enforce rate limits and manage free and premium service tiers.

  Fix: Plan for rate limits and implement error handling for situations in which usage exceeds the applicable limit.

• Assuming the key's location is interchangeable for every API.

  The vendor extracts the key from the location expected by its API.

  Fix: Follow the vendor's specified request format.

Applying the Model

Practical Design Notes

When building an application that uses a vendor API, plan how you will obtain, store, and use the API key. Also anticipate the vendor's rate limits and implement error handling for situations in which those limits are exceeded. If you use multiple keys for different applications, independent tracking can help you see which application is consuming the most resources.