Índice do curso
Lição 02 — O pedido chega à API
Por Dorian Chávez · cofundador e Chief Executive Officer da Hábil ·
O que será alcançado: que um pedido da loja entre na rota pela internet e chegue à API de pedidos, e entender o que a API responde em cada caso. É a primeira vez que a integração fala com outro sistema.
Antes de começar é preciso ter: a lição 01 concluída e o ambiente da 00 ligado:
docker compose -f infra/compose.yaml up -d --wait # desde la carpeta raíz de la práctica
A novidade de hoje, em uma frase
Na lição 01 a estação de entrada era uma pasta. Hoje é um endereço HTTP: a loja manda o pedido como quando o navegador manda um formulário, e a rota o reenvia para a API de pedidos da mesma forma.
HTTP, o mínimo: um programa manda a outro uma requisição com um método (POST é «aqui vai algo novo»),
um endereço (/ordenes), alguns cabeçalhos (dados sobre a mensagem, como etiquetas em um envelope) e um corpo
(o pedido). O outro responde com um código de três algarismos e o próprio corpo. Para saber mais, há a ficha
conceptos/antes-de-empezar/.
1. Prepare a pasta
cd lecciones/02-la-orden-llega-a-la-api
cp -R inicio mio
cd mio
2. Leia a rota
Abra orden-a-api.camel.yaml. Tem cinco passos:
POST /ordenes → sacar el id de la orden → traducir → POST a la API → anotar lo que contestó
| Passo no YAML | O que faz |
|---|---|
from: platform-http:/ordenes com httpMethodRestrict: POST |
A estação de entrada. Abre o endereço /ordenes; o parâmetro httpMethodRestrict faz com que só aceite POST. A porta 8080 não é a rota que define: quem a abre é herramientas/camel |
setHeader com name: Idempotency-Key e a expressão jsonpath "$.orden" |
Tira o número do pedido ("orden": "1001") e o coloca em um cabeçalho chamado Idempotency-Key. É a chave com que a API reconhece um pedido que já recebeu |
to: jsonata:…/mapeo.jsonata |
Traduz o pedido do formato da loja para o formato da API. O tradutor já vem pronto; na lição 03 ele é escrito à mão |
removeHeaders: CamelHttp* |
Apaga as etiquetas da chamada que entrou, para que não se misturem com a que vai sair |
to: http://api-pedidos:8080/pedidos |
A estação de saída. Chama a API pelo nome de serviço (api-pedidos), não por um número de IP |
Abra também datos/ordenes/orden-1001.json e mio/mappings/api/pedido/v1/mapeo.jsonata. Coloque um ao lado do outro:
que nome mudou (renglones → ?) e qual ficou igual?
3. Faça a previsão
A API de pedidos não aceita qualquer coisa: responde com um código diferente conforme o que chega. Antes de rodar, escreva em um papel que código ela deve dar em cada caso:
| Caso | A previsão |
|---|---|
| O pedido 1001 é enviado pela primeira vez | |
| O mesmo pedido 1001 é enviado outra vez | |
| É enviado um pedido sem linhas |
4. Rode a rota e mande um pedido
Em um terminal, inicie a rota:
../../../herramientas/camel run orden-a-api.camel.yaml
Na primeira vez demora mais, porque o Camel baixa o que precisa para falar HTTP. Espere a linha
Started orden-a-api.
Em outro terminal, a partir da mesma pasta mio/, faça o papel da loja e mande o pedido:
curl -i -XPOST localhost:8080/ordenes \
-H 'Content-Type: application/json' \
-d @../../../datos/ordenes/orden-1001.json
curlé um programa que faz requisições HTTP a partir do terminal.-imostra o código e os cabeçalhos da resposta, não só o corpo.-XPOSTé o método.-Hacrescenta um cabeçalho.-d @archivomanda esse arquivo como corpo.
Veja os dois terminais. No da rota aparecem Recibí la orden 1001 e La API contestó …. Agora pergunte à
API o que ela guardou; ela vive na porta 8081:
curl localhost:8081/pedidos/1001
5. Compare com a previsão
Mande o mesmo pedido uma segunda vez e repare no código. Depois teste um pedido sem linhas: copie o pedido,
troque o número ("orden": "1002", para que seja um pedido novo), deixe as linhas vazias e mande.
cp ../../../datos/ordenes/orden-1001.json sin-renglones.json # en tu editor: "orden": "1002" y "renglones": []
curl -i -XPOST localhost:8080/ordenes -H 'Content-Type: application/json' -d @sin-renglones.json
| Caso | O que a API responde | O que significa |
|---|---|---|
| Primeira vez | 201 | Created: «criei» |
| O mesmo pedido outra vez | 200, com ya_existia |
«Já o tinha; não dupliquei». A API reconheceu a chave |
| Sem linhas | 422 | «Entendi o que foi enviado, mas não faz sentido»: um pedido sem itens não pode ser registrado |
Sem a chave Idempotency-Key |
400 | «Falta algo obrigatório» |
| A mesma chave com outro conteúdo | 422 | «Esta chave já foi usada com algo diferente». Veja o type do corpo |
Esta tabela é o contrato da API do curso. Do rascunho do IETF para Idempotency-Key ela toma o 400 sem
chave e o 422 por chave reutilizada; o 201 e o 200 são decisão desta API, porque o rascunho não os fixa. E outra
diferença: no rascunho a chave é uma cadeia com aspas ("1001"); aqui vai sem aspas, igual ao número
do pedido. Uma API que seguisse o rascunho ao pé da letra a pediria entre aspas: antes de integrar, lê-se o
contrato dela.
Quando algo dá errado, a API responde com um JSON de erro de forma padrão (Problem Details, o tipo
application/problem+json): traz type, title, status e detail. O type é o que distingue um 422 de outro.
As duas últimas não foram testadas. Como provocar um 400? Dica: que linha da rota coloca a chave? E se o pedido 1001 for enviado com outra quantidade? A resposta é 422, igual à do pedido sem linhas. Como distinguir os dois? Veja o corpo da resposta. Faça os testes e depois devolva a rota a como estava.
Dá para ver por que o pedido sem linhas precisava de outro número? Com o 1001 haveria a mesma chave com outro conteúdo, e o 422 teria sido pela chave, não pelas linhas.
O importante do 200: se a rede falha e a loja reenvia o pedido, a API não cria dois pedidos, porque a chave diz a ela que é o mesmo. Por isso o id do pedido viaja desde a primeira estação. Na lição 18 essa mesma proteção será construída na própria integração.
6. Confira
Pare a rota com Ctrl+C (senão, a porta 8080 fica ocupada) e, a partir da pasta da lição:
cd ..
./verifica
O verifica reinicia a API para que comece vazia, inicia a rota, manda o pedido duas vezes e confere. Está concluída
quando aparecem as cinco marcas verdes:
✅ La ruta arrancó
✅ Primer envío: la API creó el pedido (201)
✅ Reenvío: la API lo reconoció y no lo duplicó (200)
✅ La API tiene el pedido 1001 con sus 2 partidas
✅ La API recibió la llave 1001: el id de la orden viajó hasta el destino
A última quem confirma é a API, não a rota: o verifica lê o que o destino anotou. A rota dizer que mandou algo
não prova que chegou; quem prova é quem recebeu. Essa ideia vai voltar muitas vezes no curso.
Não roda? ./verifica solucion testa a nossa. Se a nossa sai em verde e a própria não,
diff mio/orden-a-api.camel.yaml solucion/orden-a-api.camel.yaml mostra em que são diferentes.
| O que aparece | O que fazer |
|---|---|
El puerto 8080 está ocupado |
Ficou uma rota rodando em outro terminal: pare-a com Ctrl+C |
La API no levantó: ¿corriste la 00? |
Ligue o ambiente: docker compose -f infra/compose.yaml up -d --wait |
curl: (7) Failed to connect |
A rota ainda não iniciou: espere a linha Started |
Por que foi feito assim
O que decidimos nesta lição, com o que descartamos e o que nos faria mudar de ideia:
- A API recebe uma chave de idempotência
Revisão
- Qual é a estação de entrada desta rota, e qual a de saída?
- Para que serve o cabeçalho
Idempotency-Key, e de onde sai o valor dele? - Que diferença há entre um 201 e um 200 nesta API?
- Por que a rota chama
api-pedidose não um endereço IP? - Por que a última conferência é feita pela API e não pela rota?
A seguir: na lição 03 o tradutor deixa de vir pronto. Ele é escrito à mão, e alguns casos de teste dizem se ficou certo.
Prefere e-mail? Escreva para hola@habil.mx