Tolerant reader

As our public API evolves, integrators and clients need to adapt. The Tolerant Reader pattern makes a client resilient to those changes. By adopting the Tolerant Reader pattern, integrations can better handle new information without frequent updates. This approach reduces maintenance needs.

What is a tolerant reader?

The Tolerant Reader pattern is an integration design approach. In this pattern, a client that consumes data handles changes gracefully, such as added fields or minor structure modifications. This pattern promotes forward compatibility and reduces the need for immediate updates whenever the data or service evolves.

Real-world scenario

Consider a request to GET /organizations/{organization_id}. Initially, the response might be:

{
    "id": "cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
    "parentOrganizationId": null,
    "legalName": "Empresa Teste Ltda",
    "legalDocument": "86820799000188",
    "metadata": null,
    "status": {
        "code": "ACTIVE",
        "description": null
    },
    "createdAt": "2024-02-08T16:59:31+0300",
    "updatedAt": "2024-02-08T16:59:31+0300",
    "deletedAt": null
}

Later, fields like doingBusinessAs and address may be added:

{
    "id": "cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
    "parentOrganizationId": null,
    "legalName": "Empresa Teste Ltda",
    "doingBusinessAs": "Empresa Teste",
    "legalDocument": "86820799000188",
    "address": {
        "line1": "Rua Botucatu, 10",
        "line2": "Casa B",
        "zipCode": "04023060",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR"
    },
    "metadata": null,
    "status": {
        "code": "ACTIVE",
        "description": null
    },
    "createdAt": "2024-02-08T16:59:31+0300",
    "updatedAt": "2024-02-08T16:59:31+0300",
    "deletedAt": null
}

A client that follows the Tolerant Reader pattern would handle the additional fields without issue.

Implementing a tolerant reader

Below is an example Python code snippet that processes additional fields gracefully.

def fetch_organization_info(organization_id):
    response = requests.get(f"{host}/organization/{organization_id}")
    org_info = response.json()

    # Fetch required fields
    legal_name = org_info.get("legalName", "Unknown")
    legal_document = org_info.get("legalDocument", "No document provided")

    # Handle optional fields
    doing_business_as = org_info.get("doingBusinessAs")

    # Nested address structure
    address_info = org_info.get("address", {})
    line1 = address_info.get("line1", "Address not provided")
    city = address_info.get("city", "City not provided")
    state = address_info.get("state", "State not provided")
    country = address_info.get("country", "Country not provided")

    # Display information
    print(f"Legal Name: {legal_name}, Legal Document: {legal_document}")
    print(f"Doing Business As: {doing_business_as}")
    print(f"Address: {line1}, {city}, {state}, {country}")

# Example usage
fetch_organization_info("cc15194a-6bc9-4ebb-b15d-43411a54ba4b")

In this example, get methods safely access values. This allows for flexibility when new fields appear, such as phoneNumber. The code remains functional even if a field is absent.

Overview

Integration essentials

Stability & quality

Field dictionary

Event streaming

Tolerant reader

What is a tolerant reader?

Real-world scenario

Implementing a tolerant reader

​What is a tolerant reader?

​Real-world scenario

​Implementing a tolerant reader

What is a tolerant reader?

Real-world scenario

Implementing a tolerant reader