Versionamento de API

import { z } from "zod";

export const Pedido = z.object({
  id: z.string(),
  // valores novos viram "desconhecido" em vez de quebrar a leitura
  status: z
    .enum(["aberto", "pago", "enviado", "desconhecido"])
    .catch("desconhecido"),
}); // campos desconhecidos são descartados por padrão (não use .strict())

export type Pedido = z.infer<typeof Pedido>;

export async function buscarPedido(id: string): Promise<Pedido> {
  const resposta = await fetch(`https://api.loja.com.br/v1/pedidos/${id}`);
  if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);
  return Pedido.parse(await resposta.json());
}

from enum import Enum

import httpx
from pydantic import BaseModel


class Status(str, Enum):
    ABERTO = "aberto"
    PAGO = "pago"
    ENVIADO = "enviado"
    DESCONHECIDO = "desconhecido"

    @classmethod
    def _missing_(cls, valor):
        return cls.DESCONHECIDO  # valores novos não quebram a leitura


class Pedido(BaseModel):  # campos desconhecidos são ignorados por padrão
    id: str
    status: Status


def buscar_pedido(pedido_id: str) -> Pedido:
    resposta = httpx.get(f"https://api.loja.com.br/v1/pedidos/{pedido_id}", timeout=3)
    resposta.raise_for_status()
    return Pedido.model_validate(resposta.json())

package loja

import (
	"encoding/json"
	"fmt"
	"net/http"
)

type Status string

const (
	Aberto  Status = "aberto"
	Pago    Status = "pago"
	Enviado Status = "enviado"
)

// Conhecido diz se o cliente sabe tratar o status; valores novos chegam intactos.
func (s Status) Conhecido() bool {
	switch s {
	case Aberto, Pago, Enviado:
		return true
	}
	return false
}

type Pedido struct {
	ID     string `json:"id"`
	Status Status `json:"status"`
}

func BuscarPedido(cliente *http.Client, id string) (Pedido, error) {
	var p Pedido
	resposta, err := cliente.Get("https://api.loja.com.br/v1/pedidos/" + id)
	if err != nil {
		return p, err
	}
	defer resposta.Body.Close()
	if resposta.StatusCode != http.StatusOK {
		return p, fmt.Errorf("HTTP %d", resposta.StatusCode)
	}
	// encoding/json ignora campos desconhecidos (não use DisallowUnknownFields aqui)
	return p, json.NewDecoder(resposta.Body).Decode(&p)
}

import com.fasterxml.jackson.annotation.JsonEnumDefaultValue;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.json.JsonMapper;

public class ClienteDePedidos {
    enum Status { aberto, pago, enviado, @JsonEnumDefaultValue desconhecido }

    @JsonIgnoreProperties(ignoreUnknown = true)
    record Pedido(String id, Status status) {}

    // Valores de enumeração desconhecidos viram o valor marcado como padrão
    private static final JsonMapper MAPPER = JsonMapper.builder()
        .enable(DeserializationFeature.READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE)
        .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
        .build();

    static Pedido ler(String json) throws Exception {
        return MAPPER.readValue(json, Pedido.class);
    }
}

using System.Text.Json;
using System.Text.Json.Serialization;

public static class ClienteDePedidos
{
    // Campos desconhecidos já são ignorados por padrão no System.Text.Json
    private static readonly JsonSerializerOptions Opcoes = new()
    {
        PropertyNameCaseInsensitive = true,
        Converters = { new EnumTolerante<Status>(Status.Desconhecido) },
    };

    public static Pedido? Ler(string json) => JsonSerializer.Deserialize<Pedido>(json, Opcoes);
}

// Lê valores novos como um valor padrão, em vez de lançar exceção
public sealed class EnumTolerante<T>(T desconhecido) : JsonConverter<T> where T : struct, Enum
{
    public override T Read(ref Utf8JsonReader leitor, Type tipo, JsonSerializerOptions opcoes) =>
        Enum.TryParse<T>(leitor.GetString()?.Replace("_", ""), ignoreCase: true, out var valor)
            && Enum.IsDefined(valor) ? valor : desconhecido;

    public override void Write(Utf8JsonWriter escritor, T valor, JsonSerializerOptions opcoes) =>
        escritor.WriteStringValue(valor.ToString().ToLowerInvariant());
}

public enum Status { Desconhecido, Aberto, Pago, Enviado }
public record Pedido(string Id, Status Status);