Skip to main content

API Versions

The Versioning page outlines the versioning approach adopted by the CodeNOW API. To maintain backward compatibility and allow for future enhancements, the API follows the MIME type versioning strategy at the operation level.

MIME Type Versioning​

In MIME type versioning, the API version is specified in the Accept header of the HTTP request. Each API operation supports multiple versions, and clients can indicate the desired version in their requests. By including the version in the Accept header, developers can control which API version their application interacts with, ensuring smooth transitions between updates.

Versioning Format​

The versioning format in the Accept header follows the pattern application/vnd.codenow.vX+json, where X represents the desired version number. For example, to request version 1 of an API operation, the Accept header would be:

Accept: application/vnd.codenow.v1+json

Forward Compatibility​

Maintaining forward compatibility is a core principle of the CodeNOW API. Forward compatibility ensures that clients using older API versions can continue to function seamlessly even as new versions are introduced. Any changes made to the API are designed to be non-breaking for older clients, reducing the risk of disrupting existing implementations.

Breaking Changes​

Breaking changes are introduced only in new versions of the MIME type. When a breaking change becomes necessary for future improvements or to address limitations in older API versions, the API team introduces a new major version of the MIME type. This approach allows clients to prepare and transition their applications smoothly, knowing that breaking changes will not affect the existing API version they are using.

Breaking changes include:

  • removing an entire operation
  • removing or renaming a parameter
  • removing or renaming a response field
  • adding a new required parameter
  • making a previously optional parameter required
  • changing the type of a parameter or response field
  • removing enum values
  • adding a new validation rule to an existing parameter
  • changing authentication or authorization requirements

Non-Breaking Changes​

Non-breaking changes encompass additions, updates, and optimizations to existing API endpoints that do not affect the current behavior of client applications using older versions. These changes are designed to be fully backward compatible, ensuring a seamless experience for users and applications.

Non-Breaking changes include:

  • adding an operation
  • adding an optional parameter
  • adding an optional request header
  • adding a response field
  • adding a response header
  • adding enum values

Upgrading to Newer Versions​

Developers are encouraged to regularly review the API documentation, changelog, and upgrade guides to stay informed about new versions and improvements. Upgrading to newer versions of the API unlocks access to new features, enhancements, and optimizations.

Example API Request with Versioning​

Here's an example of how to make an API request with MIME type versioning:

curl -X GET \
  -H "Accept: application/vnd.codenow.v1+json" \
  -H "X-Codenow-Api-Key: Bearer YOUR_API_KEY" \
  https://api.codenow.com/environments

In this example, the client specifies the desired version 1 of the /environments endpoint by including Accept: application/vnd.codenow+json; version=1 in the request headers.

Let's Code Forward​

With MIME type versioning and a commitment to forward compatibility, the CodeNOW API empowers developers to confidently build and evolve their applications while leveraging the latest features and enhancements. Embrace versioning, stay up-to-date, and let's code forward together!