Lendo um Service Domain até o OpenAPI
O caminho de cada endpoint, o mapeamento para HTTP e o que fica para a sua implementação.
5 min de leitura
Assista ao documentário do curso (~24 min)Abrir um YAML do BIAN pela primeira vez dá a sensação de que a API já está pronta: caminho, método, schema, tudo ali. Não está. O que o BIAN publica é o contrato semântico; quem decide autenticação, idempotência, versão e modelo de erro é você. Esta aula ensina a ler um Service Domain até o OpenAPI sabendo exatamente onde a especificação termina e onde a sua implementação começa.
A anatomia do caminho
Todo endpoint dos YAMLs da v14 tem a mesma forma:
/{ServiceDomain}/{crId}/{BehaviorQualifier}/{bqId}/{ActionTerm}
Cada segmento aponta para uma camada do mapa que você viu na aula 02. O primeiro é o Service Domain. O segundo identifica uma instância do Control Record. O terceiro é o Behavior Qualifier, a parte do Control Record que a operação toca. O quarto identifica uma instância desse qualifier. O quinto é o action term da aula 03: o verbo.
Pegue o Current Account na v14 como referência. Ele segue o padrão funcional Fulfill, o Control Record se chama CurrentAccountFacility, a especificação lista 34 operações e 9 Behavior Qualifiers, e o nome proposto no alinhamento com ISO 20022 é CashAccountService. Quando você lê /CurrentAccount/{id}/..., está lendo: um domínio, uma conta, uma faceta dessa conta, um evento nessa faceta, uma ação.
O que o caminho não carrega: tenant, canal, versão, ambiente. Nada disso está no YAML, e é de propósito. O BIAN descreve o que o banco faz, não como a sua empresa publica isso. Guarde essa frase: ela explica tudo o que vem no fim da aula.
A leitura que recomendo: trate o caminho como o mapa dobrado numa URL. Se um segmento não corresponde a uma camada do mapa, ou você leu errado ou alguém inventou um segmento.
Cada segmento do caminho aponta para uma camada do mapa
Exemplo real da v14: PUT /CurrentAccount/{crId}/DebitandCredit/{bqId}/Execute. Os cinco segmentos vêm do BIAN; o que está no grupo de baixo é responsabilidade sua.
- /CurrentAccount
- /{crId} · uma conta
- /DebitandCredit
- /{bqId} · um movimento
- /Execute
- Service Domain · Current Account (Fulfill)
- Control Record · CurrentAccountFacility
- Behavior Qualifier · 1 de 9
- Action Term · Execute
- Método HTTP · YAML v14: PUT
- Auth, Idempotency-Key, · versão, erro, SLO
Lendo /CurrentAccount/{id}/DebitandCredit/{id}/Execute segmento a segmento
- 1
/CurrentAccount
O Service Domain. Padrão Fulfill: ele cumpre um produto já contratado. Na leitura DDD, é o bounded context candidato.
- 2
/{id} (primeiro)
O crId: uma instância de CurrentAccountFacility, ou seja, uma conta específica. Tudo depois deste segmento acontece dentro dessa conta.
- 3
/DebitandCredit
O Behavior Qualifier, um dos 9 do Current Account. É a faceta do Control Record que trata lançamentos de débito e crédito.
- 4
/{id} (segundo)
O bqId: um lançamento específico dentro daquela conta. Não é um agregado próprio; vive dentro do Control Record.
- 5
/Execute
O action term. Nos YAMLs da v14 vira PUT. Executar um lançamento é a ação que move dinheiro, e é exatamente aqui que idempotência deixa de ser detalhe.
Do action term ao método HTTP, e os quatro sabores
O mapeamento nos YAMLs da v14 é fixo e vale a pena decorar: Retrieve vira GET, Initiate vira POST, e Update, Execute e Exchange viram PUT. A lógica é a do HTTP: Initiate cria uma instância (POST), Retrieve lê (GET), e os três últimos agem sobre uma instância que o caminho já identifica (PUT).
Essa escolha tem uma consequência que o YAML não discute. PUT, pela semântica do HTTP, é idempotente: repetir a chamada deveria dar o mesmo resultado. Um Execute de débito repetido não é naturalmente idempotente. Então o BIAN entrega um método que promete idempotência e você precisa cumprir a promessa, com chave de idempotência e armazenamento do resultado. Isso volta no bloco final.
Os quatro sabores de publicação. A mesma semântica sai em quatro formas: REST ou assíncrona, cada uma com o Business Object Model do próprio BIAN ou com mensagens ISO 20022. São dois eixos, não quatro padrões diferentes. O que muda é o transporte e o vocabulário dos payloads; o que não muda é o Service Domain, o Control Record e o action term.
Minha regra: REST com Business Object Model quando a API é interna e consumida por times de produto; ISO 20022 quando a mensagem atravessa a fronteira do banco para trilho ou parceiro, que é o caso do Pix na aula 05. Assíncrono quando a operação não cabe no tempo de uma requisição ou quando o consumidor precisa de evento, não de resposta.
Leia o caminho
Action term x método HTTP nos YAMLs da v14
| Action term | Método HTTP | O que faz | O que fica com você |
|---|---|---|---|
| Retrieve | GET | Lê uma instância do Control Record ou do Behavior Qualifier | Paginação, filtros e cache; o YAML não os define |
| Initiate | POST | Cria uma nova instância | Idempotência de criação e geração do id |
| Update | PUT | Altera uma instância existente | Controle de concorrência e auditoria da mudança |
| Execute | PUT | Executa a ação de negócio na instância | Idempotency-Key obrigatória; é onde o dinheiro se move |
| Exchange | PUT | Aceita, rejeita ou responde a uma instância | Autorização por papel: quem pode aceitar o quê |
Leitura DDD e o que fica com você
Se você vem de Domain-Driven Design, a tradução é curta. O Service Domain é um bounded context candidato. Candidato, não decreto: a aula 07 mostra que um Service Domain pode virar dois sistemas e três Service Domains podem morar num só. O Control Record é o aggregate: a fronteira de consistência. O Behavior Qualifier vive dentro dele, por isso DebitandCredit/{id} não é um agregado separado, é uma entidade dentro de CurrentAccountFacility.
Essa leitura resolve uma dúvida frequente: "posso ter uma transação que toca dois Control Records?". Pode, mas ela atravessa dois agregados, e isso é saga ou orquestração, não uma chamada só. O caminho do BIAN deixa isso visível: cada URL toca um crId.
Agora a lista do que o YAML não resolve e que é sua responsabilidade escrever no OpenAPI que vai para o gateway:
- Autenticação: o esquema de segurança (OAuth 2, mTLS) não está no YAML.
- Autorização: quem pode chamar Execute em qual conta. Isso é regra de negócio e de regulação.
- Idempotência: chave por chamada em Initiate e Execute, com resultado armazenado.
- Versionamento: no caminho ou no header, mas em algum lugar, porque a v14 não põe versão na URL.
- Modelo de erro: um formato único para todos os domínios;
problem+jsoné a minha escolha padrão. - Paginação: Retrieve de coleções precisa de cursor ou offset.
- SLO: latência e disponibilidade por operação, porque Retrieve e Execute não têm o mesmo custo de falha.
A analogia para quem programa: o BIAN entrega a interface; a classe que implementa é sua.
Na prática, eu uso o YAML do BIAN como gabarito de nomes e de fronteira, nunca como o arquivo que vai para o gateway. Copio o caminho, mantenho o action term e o método, e escrevo o meu OpenAPI por cima: security scheme, header de idempotência, versão e um único modelo de erro. Time que publica o YAML cru acaba com um modelo de erro por domínio e sem resposta para "quem pode chamar Execute". O custo não aparece na primeira entrega; aparece na auditoria.