Skip to main content

API design approach

We adhere to industry-standard conventions, allowing you to use familiar tools seamlessly. Our APIs are designed for self-service, guiding you through the next steps with ease. They are intuitive, well-documented, and backed by certifications to support smooth and secure integration.

To further enhance usability, we maintain consistent language across all services. This ensures a seamless experience, allowing you to quickly navigate and integrate different APIs without having to adapt to new terminology or conventions. The result is improved learnability, faster integration, and greater efficiency.

Secure by Design​

1GLOBAL strives to implement best of breed security controls to its products and services. 1GLOBAL Connect API has considered security by design since it’s conception. This ensures that all layers from servers to data and source code follow a security by design approach.

1GLOBAL ensures all servers running Connect have a secure architecture and are securely hardened with configurations aligned with international and recognized standards.

Additionally, 1GLOBAL implements a strict vulnerability management program that continuously monitors for potential attack vectors along with the execution of periodic penetration tests to test our defences.

Knowing that preventive controls are just a part of the security puzzle, 1GLOBAL also operates a continuous monitoring and security incident response capability, within from our Cyber Defence Centre.

Hypertext Application Language (HAL)​

HAL standardizes the format of API resources and links, making it easier to navigate and interact with our APIs. By providing a consistent approach to hyperlinking between API resources, HAL allows seamless integration between different APIs, offering a more consumable and explorable experience.

One of HAL’s key advantages is that it is both machine-readable and human-readable, enabling you to quickly grasp the context from the API reference documentation.

We adopt this convention to structure resource and action links, ensuring compatibility with standard libraries for smoother and more efficient development.

{
  ...
 "_links": {
    "self": {
      "href": "https://example.com/probs/1234"
    },
    "author": {
      "href": "https://example.com/users/john"
    }
  }
}

Pagination​

To protect the service against overload, as well as to support client side iteration and batch processing experience, resource listing endpoints implement cursor-based pagination.

The only input required is the page size (using limit parameter) and subsequent navigation can be done through the next/prev page links provided in each page's response payload.

To prevent misuse of the pagination feature, each API defines a maximum allowed page size (usually 50 or 100).

{
  ...
  "_links": {
    "self": { "href": "https://example.com/probs?limit=10" },
    "prev": { "href": "https://example.com/probs?cursor=MTY3NjE1ODU1MS8yNUMxOTgxRjA1RDU5MDAwMDAwMA%3D%3D&limit=10" },
    "next": { "href": "https://example.com/probs?cursor=MTY3NjEzMzkxMS8yNUMxMEYzNkJBODA1NTkwMDAwMDAw&limit=10" },
  }
}

Headers​

  • Correlation-ID: In order to easily identify a request on all of 1GLOBAL's subsystems, we require that requesters create a unique identifier that will be sent on every request header when (Correlation-Id) using the api. This way we can easily identify a request or a sequence of events between both 1GLOBAL and the requester.

Compatibility​

1GLOBAL strives to maintain backward compatibility across its APIs to provide a consistent experience for clients. However, there are instances where introducing breaking changes becomes necessary to implement new features, improvements, compliance reasons or architectural updates, in that cases, a new version of the API will be made available. We follow a Header Versioning approach, combined with data-based versioning, to ensure that clients can smoothly transition to the updated version without disrupting their current integrations. Clear documentation, migration guides, and deprecation timelines will always accompany these changes to minimize any potential impact.

Clear documentation, migration guides, and deprecation timelines will always accompany these changes to minimize any potential impact.

Any additive (non-breaking) changes will be incorporated into all supported API versions, ensuring compatibility while providing access to new features.

Non-breaking change definition​

  • Changing the lengh or format of identifiers including changing or removing prefixes
  • Adding new optional request parameters to existing APIs
  • Adding new properties to existing API responses
  • Adding new HTTP headers ( optional request and response )
  • Increasing the lenght of existing string field values
  • Adding new enumerate values
  • Adding new error codes
  • Changing error messages
  • Adding new webhooks eventy types ( you might need to explicility opt into these )
  • Adding new properties to existing webhook event schemas
  • Adding new links and relationship types
  • Changing FQDNs/path in links
  • Reordering elements
  • Adding new API resources

API Version Lifecycle​

Each API version follows a defined lifecycle:

Our API evolves through well-defined stages to ensure reliable functionality and improvements over time. Here’s an overview of the lifecycle:

  1. Design and Planning: During this stage, we outline the API’s purpose, audience, and architecture to meet the needs of developers.
  2. Development: APIs are built with performance, security, and scalability in mind, following best practices.
  3. Testing: Extensive testing ensures the API operates as expected and is free of critical issues.
  4. Release: The API is officially published along with complete documentation for developers to begin integration.
  5. Maintenance: We continuously monitor, support, and enhance the API, addressing bugs and implementing improvements.
  6. Deprecation and Sunset: Older API versions are gradually retired as newer versions or alternatives

Phases of API Deprecation​

To minimize disruption to your developers, we follow a structured deprecation process when retiring an API version:

1. Announcement​

We notify partners about deprecation through public announcements (e.g., blog posts, changelogs, newsletters) and programmatic notices (e.g., Deprecation headers in API responses).
A deprecation timeline is provided, outlining key dates such as the start of deprecation and the end-of-life/removal.
Clear migration paths or alternatives are shared in the documentation to facilitate the transition.

2. Support Phase​

During this phase, we provide tools and resources to ease the transition:

  • Deprecation Headers: API responses include a Deprecation HTTP header that indicates timestamp at which a replacement will become/became available. Example:

    Deprecation: Wed, 31 Dec 2025 23:59:59 GMT

  • Sunset Headers: API responses include a Sunset HTTP header that indicates the exact end-of-life date, after which the functionality will become unresponsive. Example:

    Sunset: Wed, 31 Dec 2025 23:59:59 GMT

  • Deprecated Status: The affected version is marked as deprecated but remains functional during this phase.

  • Migration Guides: We offer documentation, tools to aid in the transition.

  • Monitoring and Feedback: Usage analytics help us identify users who may need additional support.

3. Gradual Removal​

The deprecated version is phased out through:

  • Rate Limiting: Reducing the rate limit for deprecated endpoints.
  • Usage Alerts: Notifying partners of continued usage as the end-of-life date approaches.
4. Termination​

The deprecated version is fully removed. Any requests to it will no longer be served. Final notices and updates are posted across communication channels. Transitional support is provided for affected users on a case-by-case basis.

  • HTTP Status Codes: After removal, unsupported requests may return 410 Gone.

Example HTTP Response:​

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "status": 410,
  "title": "Deprecated Resource"
  "detail": "The requested resource has been deprecated and is no longer available."
  "deprecated_at": "2025-03-18T23:59:59Z",
  "sunsetted_at": "2026-03-18T23:59:59Z",
  "documentation": "https://api.example.com/deprecation-guide"
}

Errors​

Connect API follows standard HTTP status codes to communicate error information in a consistent and compliant manner following RFC7807

  • HTTP status codes will be 4xx or 5xx when there's a problem
  • The body of the response will be a JSON object
  • The errors property contains an array giving specific details of one or more errors that occurred.

Status codes in the 4xx range​

These status codes indicate an issue with the request that needs to be resolved. Once the issue is fixed, you can safely retry the call. Common examples include authentication errors (HTTP status code 401) or request body validation errors (HTTP status code 400).

Status codes in the 5xx range​

These errors typically indicate server-side issues, ranging from configuration problems (which may be specific to a merchant or entity) to internal network connectivity issues. They can be transient, affecting only a single call, or persistent, impacting multiple calls over an extended period. In most cases, callers will be unable to resolve these issues on their own. The most common example of 5xx errors is timeouts.

Example​

{
    "title": "Invalid request parameters",
    "status": 400,
    "detail": "Invalid request parameters",
    "errors": [
        {
            "code": "MISSING_CONDITIONAL_MANDATORY_FIELD",
            "detail": "Field(s) [first_name, last_name, email, address] cannot be null when field [id] is equal to [null]",
            "json_path": "$.subscriber.id"
        },
        {
            "code": "GENERIC_ERROR",
            "detail": "must not be empty",
            "json_path": "$.purchase_location"
        }
    ],
    "correlation_id": "daaccc90-dd03-471c-a892-0e8c5ec27026"
}