Client Policy

This document defines the commitments that callers of the AX Hub SDK can rely on. The SDK is a library that lets you call the AX Hub backend from code.

1. Overview

The AX Hub SDK ships in six languages: node, go, java, kotlin, python, ruby. The six SDKs call the same backend the same way; only names and syntax follow each language.

All six SDKs are generated from a single backend OpenAPI specification. An OpenAPI specification is a machine-readable document that describes the request and response shapes of an API. The contract (the specification) is defined first, and the SDK code is generated from that contract. That is why the six languages never diverge in behavior.

This document defines the commitments that callers of the SDK can rely on. It states what stays the same across version bumps and what may change without notice. The paths, parameters, and response fields of individual APIs are not in this document; they are in the SDK API Reference.

Changes to this document are recorded in the revision history in section 10.

2. Versioning Policy

Independent versions per language

Each language SDK follows SemVer independently. SemVer is a rule that assigns versions with three numbers, major.minor.patch (for example, 2.4.1). Because release timing differs per language, the version number for the same feature may differ from one language to another. For example, when the python SDK is at 1.3.0, the go SDK may be at 1.5.0.

Tiered stability

What is stable and what may still change is split into two tiers.

The route surface means the full list of API endpoints the SDK provides.

The terms in Tier 1 are, in brief, as follows. How each item actually behaves is covered in section 4, Stable Contracts.

• camelCase: notation like hasMore that joins words by capitalizing the word boundary.
• PAT: an API key issued to an individual (Personal Access Token).
• JWT: a signed token received after login.
• X-Request-ID: a tracing ID that identifies a single request.
• 429: the HTTP status code meaning too many requests (rate limit).

What 1.0 means

1.0 is the point at which the conformance check corpus is frozen. The conformance corpus is a set of tests that checks whether the six SDKs behave the same on the same input. Once this set is fixed, the Tier 2 items also become stable contracts.

0.x rules

Before 1.0 (in 0.x), the list of APIs may change in a minor version. When it changes, the CHANGELOG states what was added, removed, or renamed.

3. Compatibility Guarantees

Changes are split into two kinds. A breaking change is one that requires a major version bump. A non-breaking change is one that may happen at any time in a minor or patch release.

breaking (bumps the major version)

• removing or renaming an existing operationId (after 1.0). An operationId is the unique name that identifies each API.
• changing the meaning of an error code or category.
• changing the response-key notation rule.
• changing an authentication method.

non-breaking (can happen at any time)

• adding an API.
• adding a response field.
• adding an error code.
• changing the wording of an error message.

Client obligations

To keep non-breaking changes from breaking your code, the caller of the SDK must follow two rules.

First, ignore unknown response fields. If a new field appears in a response, leave it as-is. Do not treat an added field as an error.

Second, branch on errors using only code and category. Do not depend on the message string. The wording of a message changes without notice.

# Bad — depending on the message string
if "already exists" in e.message:
    ...

# Good — branching on code
if e.code == "slug_taken":
    ...

4. Stable Contracts

The items in this section are safe to code against. All are Tier 1, so changing them bumps the major version.

Error object

When an error occurs, the SDK returns an error object holding the fields below.

message is not in this list. message is not a stable contract. As stated in section 3, do not use it for branching.

Response-key notation

Response keys are converted to camelCase. Even when the backend returns has_more, the SDK converts it to hasMore.

There is one exception. In this case the keys are left in their original form, not converted.

• The row-internal keys of app-DB row reads (the column names of user-created tables) are left as-is. Column names belong to the user, so the SDK does not touch them.

Authentication

There are two kinds of authentication token. Either way, the SDK carries it in a header.

• A PAT is sent in the X-Api-Key header.
• A JWT is sent in the Authorization: Bearer header.

When you create a token, you must state the tokenType. tokenType is the value that tells whether the token is a PAT or a JWT. The SDK never guesses the token kind on its own.

Request tracing

An X-Request-ID is attached to every request automatically. If you include this value when you contact support, the corresponding request can be traced.

Retry

A 429 response is retried automatically. In that case the SDK waits for the Retry-After value the server returned and retries up to 2 times. Retry-After is the retry wait time the server reports. Statuses other than 429 are not retried automatically.

5. Deprecation

deprecated means marking a feature in advance as scheduled for removal soon.

Feature removal happens only in a major release. Features are not removed in a minor or patch release.

Before removal, three things are honored.

• Mark it as deprecated in the CHANGELOG and the documentation.
• Announce it at least 90 days in advance.
• Provide a migration note with the replacement approach.

6. Support Scope

Minimum runtime

The minimum execution environment each SDK requires. LTS means the Long-Term Support version.

Distribution channels

Each SDK is obtained from the standard repository for its language.

Supported versions

Only the latest major version is supported. Previous major versions are not supported.

7. Security

Token handling

Tokens are not written to logs or error reports. If a token leaks, the account is exposed.

When diagnostic information needs a token, use redactedToken(). This function always returns ***REDACTED*** instead of the real token.

Reporting vulnerabilities

Vulnerabilities are reported only through a GitHub Private Security Advisory. A Private Security Advisory is a GitHub channel for reporting security issues privately. Do not open a public issue. Receipt is acknowledged within 3 business days.

8. Client Responsibilities

The SDK handles most protocol details for you. However, the two items below are not done for you by the SDK. The caller must handle them directly.

Detailed usage of each endpoint is in the SDK API Reference.

9. Support Channels

10. Revision History