Determining the version of an API is an important step in working with it. The version indicates what features and functionality are available and how to properly interact with the API. Unfortunately, there is no universal standard for where API version information is located. It may be in the API documentation, evident from the endpoint URL structure, or returned in response metadata. This article will explore the common places to check for API version and provide guidance on discovering it for any new API.
Check the Documentation
The first place to look when trying to identify an API’s version is its documentation. Many API providers will explicitly state the version in the introduction or overview section of the docs. For example, the Stripe API docs clearly show “Version: 2020-08-27” at the top of the Introduction page.
If the API documentation doesn’t call out the version right away, look for a changelog or release notes. Often there will be a page detailing each version released and the changes made in each one. The most recent version in the changelog is most likely the current default version.
As a last resort in the documentation, look for indications of version in code samples or usage examples. For instance, the version may be included in cURL request headers or request body parameters. Examining a few different example requests can shed light on the API version expected for general use.
Tips for checking documentation:
- Read the introduction and overview pages closely
- Scan the table of contents for a changelog or release notes
- Examine code samples for version indicators in headers or parameters
Look at the Endpoint URL Structure
Many REST APIs encode the version directly into the endpoint URLs. A common pattern is to include it as a path segment such as:
“`
https://api.example.com/v1/users
https://api.example.com/v2/users
“`
The version is also sometimes appended as a query parameter, like:
“`
https://api.example.com/users?version=2
“`
If the API documentation doesn’t explicitly call out the version, look closely at the endpoint URLs provided. The path segments and query parameters often contain version clues.
Some APIs maintain multiple active versions, so you may see endpoints for v1, v2, etc. Try making requests to endpoints from different versions and observe the response. This can confirm which is the current default version.
Tips for checking endpoint URLs:
- Inspect the path segments for version numbers
- Check for a “version” query parameter
- Attempt requests across versions to identify the current default
Examine Response Metadata
For APIs that don’t include the version in endpoint URLs, the version information may be contained in HTTP response metadata.
Many APIs return custom response headers that indicate the version. Check the documentation for any header specifications. For example, Twilio returns a `Twilio-Api-Version` header on all responses:
“`
Twilio-Api-Version: 2010-04-01
“`
If the API doesn’t define custom headers, look for standard headers that may reveal the version:
“`
X-Api-Version: 1.0
“`
Beyond headers, some APIs include the version directly in the response body. The metadata may be returned in a top level “version” field or alongside other metadata like the response timestamp.
Tips for examining response metadata:
- Check docs for custom version headers
- Inspect standard headers like X-Api-Version
- Look in response body for a top level version field
Issue an Options Request
For REST APIs, an OPTIONS request can be useful for extracting metadata including version information. This request queries the server for details on the available HTTP methods and options for a given endpoint.
The response will include an Allow header listing permitted methods, and may also return API version headers:
“`
Allow: GET, POST, PUT, DELETE
X-Api-Version: 1.1.0
“`
Try an OPTIONS request on a few different endpoints to see if the version headers are consistent.
One downside to this technique is that OPTIONS requests may be disabled on some APIs. The request will return a 405 Method Not Allowed error if OPTIONS is not enabled.
Tips for OPTIONS requests:
- Query OPTIONS on endpoints to get API capabilities
- Check Allow header for enabled HTTP methods
- Inspect response headers for version metadata
Use the API SDKs
For APIs with client SDKs (software development kits), the SDK source code and documentation can reveal the API version.
SDKs are often named or versioned to match the underlying API. For example, “stripe-python v20.8.0” indicates it integrates with Stripe API version 2020-08-27.
Look in the SDK readmes and integration docs for notes on compatible API versions. The release notes may also call out version mappings between SDKs and API.
If the API version is not apparent from the SDK name or docs, you can look directly in the source code. Specifically check for any hardcoded API version constants and headers in the HTTP client methods.
Tips for using API SDKs:
- Match SDK version to API version if explicitly named
- Check SDK docs for notes on API version compatibility
- Inspect SDK source code for hardcoded API version constants
Prompt the API Provider
If the API version remains unclear after exhausting the options above, reach out directly to the API provider for clarification. Look for contact information in the documentation and provide details on the API product and endpoints you are accessing.
Most providers will happily point you to the current default version. Their support channels may also provide advice on handling version upgrades and migrations.
Some key details to include in your inquiry:
– API product name
– Endpoints accessed
– SDKs or tooling used
– Example request IDs for reference
Hopefully the response will clearly identify the elusive API version. This should be the last resort after thoroughly checking the other avenues outlined above.
Tips for prompting the API provider:
- Consult API docs for support contact info
- Provide API product name and endpoints in use
- Include relevant SDKs/tools and example request IDs
- Ask for current default version info
Conclusion
Identifying the version is a key first step in working with any API. By following the strategies outlined in this article, you can track down version information for even the most opaque APIs.
Check documentation closely, inspect endpoint URLs, examine metadata headers, try OPTIONS requests, leverage SDKs, and ask the provider when needed.
Discovering the API version ensures you use the right feature set and prevents incorrect assumptions about available functionality. Taking the time to pinpoint version can save hours of frustration down the road.
With these handy tips, you can confidently explore and integrate with new APIs knowing you can find the version when needed.