API Versioning

The Prahsys API uses a comprehensive versioning system that maintains backward compatibility while delivering new capabilities. This page explains our versioning approach and how to specify API versions in your requests.

Versioning Scheme

Our API uses a dual versioning approach that separates API namespaces from API versions:

• API Namespace (n1, n2, etc.): The URL path includes a namespace that represents the architecture and structure of the API. The namespace is not a version - it’s a way to organize different API structures that may exist concurrently.

• Semantic API Versioning (via headers): Independent from the namespace, we use semantic versioning to track specific implementation changes:

  • Major versions (X.0.0): Potentially breaking changes that require code updates
  • Minor versions (1.X.0): New features and enhancements that are backward-compatible
  • Patch versions (1.0.X): Bug fixes and maintenance updates that are backward-compatible

Namespaces vs. Versions

Namespaces (n1, n2, etc.) and versions (1.2.3, 1.3.0, etc.) serve different purposes:

• Namespaces define the API structure, endpoint organization, and design patterns. A new namespace is introduced when we need fundamental architectural changes or new design patterns that can’t be accommodated within the existing structure.
• Versions control the behavior and implementation details within a namespace structure while maintaining the same overall design pattern.

Key characteristics of this approach:

• Co-existing Namespaces: Multiple namespaces (n1, n2, etc.) can exist and operate simultaneously, allowing for gradual migration between architectural styles.
• Design Pattern Differences: The primary purpose of separate namespaces is to accommodate different API design patterns (e.g., resource-oriented vs. action-oriented, or different authentication mechanisms).

For example, n1 may contain many different version implementations (1.0.0, 1.1.0, 1.2.3, etc.) that all use the same URL structure and design pattern while providing different functionality or behavior. Meanwhile, n2 might use a completely different architectural approach but co-exist with n1 during a transition period. The header-specified version gives you granular control over which exact implementation handles your request within a namespace.

Specifying API Version

You can specify which API version to use in two ways:

1. Request Header (Recommended)

Include the X-Prahsys-Version header in your API requests to specify the exact API version you want to use:

Important: By not specifying a X-Prahsys-Version, it will always default to the latest version within the namespace.

X-Prahsys-Version: 1.2.3

Using the header gives you precise control over which version of the API handles your request, including major, minor, and patch versions. This is especially useful for ensuring consistent behavior during API transitions. Without specifying a version, your request will use the latest available version within the namespace specified in the URL path.

2. URL Path

The API path includes a namespace identifier (which is separate from the API version):

https://api.prahsys.com/n1/::path

Version Information in Responses

When you make a request, the API will include the exact version that processed your request in the response headers:

X-Prahsys-Version: 1.2.3

This response header is informational and helps with debugging by confirming which API version actually handled your request. It’s particularly useful to verify that the version you specified in your request was the one that was used.

The namespace (n1 in this example) identifies the structural organization of the API. The namespace is not a version - it’s simply a way to organize endpoints. When a new namespace is introduced (like n2), it represents a different API architecture, possibly with different endpoint structures, parameter requirements, or response formats.

Without specifying an API version in the header, you’ll get the latest version available within that namespace. This behavior lets you stay up-to-date with bug fixes and backward-compatible improvements without changing your code.

Example API Request with Version Specification

Here’s an example of making an API request that specifies a particular version:

const response = await fetch("https://api.prahsys.com/payments/n1/status", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
    "X-Prahsys-Version": "1.2.3", // Specify exact API version to use
  },
});
 
// The response headers will confirm which version was used
const apiVersionUsed = response.headers.get("X-Prahsys-Version");
console.log(`API request handled by version: ${apiVersionUsed}`);

Compatibility Policy

• Within Same Namespace: We maintain backward compatibility for minor (1.X.0) and patch (1.0.X) version changes
• Namespace Changes: When we need to introduce substantial design pattern or architectural changes to the API, we introduce a new namespace (e.g., from n1 to n2) rather than incrementing the major version
• Parallel Support: Multiple namespaces can be actively supported simultaneously, allowing you to migrate at your own pace
• Independent Evolution: Different namespaces evolve independently with their own versioning timelines

For information on all API versions and changes, please refer to our API Changelog.