Leitor tolerante

À medida que nossa API pública evolui para atender novos requisitos e aprimorar funcionalidades, integradores e clientes precisam se adaptar de forma transparente. Um padrão chave que suporta a resiliência a essas mudanças é o Leitor Tolerante (Tolerant Reader). Ao adotar o padrão Leitor Tolerante, as integrações podem lidar melhor com novas informações sem atualizações frequentes. Essa abordagem reduz as necessidades de manutenção e aumenta a resiliência, criando uma experiência de integração mais fluida.

O que é um leitor tolerante?

O padrão Leitor Tolerante é uma abordagem de design de integração em que um cliente que consome dados é construído para lidar com mudanças potenciais — como campos adicionados ou modificações menores na estrutura — de forma elegante. Esse padrão promove compatibilidade futura, reduzindo a necessidade de atualizações imediatas sempre que os dados ou o serviço evoluem.

Cenário real

Considere uma requisição para GET /organizations/{organization_id}. Inicialmente, a resposta pode ser:

{
    "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
}

Posteriormente, campos como doingBusinessAs e address podem ser adicionados:

{
    "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
}

Um cliente que segue o padrão Leitor Tolerante lidaria com os campos adicionais sem problemas, garantindo a continuidade do funcionamento.

Implementando um leitor tolerante

Abaixo está um exemplo de código Python que processa campos adicionais de forma elegante, considerando mudanças no payload.

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")

Neste exemplo, métodos get são usados para acessar valores de forma segura. Isso permite flexibilidade caso novos campos, como phoneNumber, sejam introduzidos, pois o código continua funcional mesmo se um campo estiver ausente.

​O que é um leitor tolerante?

​Cenário real

​Implementando um leitor tolerante

O que é um leitor tolerante?

Cenário real

Implementando um leitor tolerante