Course contents
Lesson 02 — The order reaches the API
By Dorian Chávez · co-founder and Chief Executive Officer of Hábil ·
What you will achieve: have an order from the store enter your route over the internet and reach the orders API, and understand what the API answers in each case. It is the first time your integration talks to another system.
Before you start you need: lesson 01 finished and the environment from lesson 00 turned on:
docker compose -f infra/compose.yaml up -d --wait # desde la carpeta raíz de la práctica
What is new today, in one sentence
In lesson 01 the input station was a folder. Today it is an HTTP address: the store sends the order the way your browser sends a form, and your route forwards it to the orders API in the same way.
HTTP, the bare minimum: one program sends another a request with a method (POST means "here is something new for you"),
an address (/ordenes), some headers (data about the message, like labels on an envelope) and a body
(the order). The other one answers with a three-digit code and its own body. If you want more, there is the card
conceptos/antes-de-empezar/.
1. Set up your folder
cd lecciones/02-la-orden-llega-a-la-api
cp -R inicio mio
cd mio
2. Read the route
Open orden-a-api.camel.yaml. It has five steps:
POST /ordenes → sacar el id de la orden → traducir → POST a la API → anotar lo que contestó
| Step in the YAML | What it does |
|---|---|
from: platform-http:/ordenes with httpMethodRestrict: POST |
The input station. It opens the address /ordenes; the httpMethodRestrict parameter makes it accept only POST. Port 8080 is not set by the route: herramientas/camel opens it |
setHeader with name: Idempotency-Key and the jsonpath expression "$.orden" |
It takes the order number ("orden": "1001") and puts it in a header called Idempotency-Key. It is the key with which the API recognizes an order it has already received |
to: jsonata:…/mapeo.jsonata |
It translates the order from the store's format to the API's format. The translator comes ready-made; in lesson 03 you write it yourself |
removeHeaders: CamelHttp* |
It deletes the labels of the call that came in, so that they do not get mixed with the one that is about to go out |
to: http://api-pedidos:8080/pedidos |
The output station. It calls the API by its service name (api-pedidos), not by an IP number |
Also open datos/ordenes/orden-1001.json and mio/mappings/api/pedido/v1/mapeo.jsonata. Put one next to the other:
which name changed (renglones → ?) and which one stayed the same?
3. Predict
The orders API does not accept just anything: it answers with a different code depending on what reaches it. Before you run, write on paper which code you think it gives in each case:
| Case | Your prediction |
|---|---|
| You send order 1001 for the first time | |
| You send the same order 1001 again | |
| You send an order with no order lines |
4. Run it and send it an order
In one terminal, start the route:
../../../herramientas/camel run orden-a-api.camel.yaml
The first time it takes longer, because Camel downloads what it needs to speak HTTP. Wait for the line
Started orden-a-api.
In another terminal, from the same mio/ folder, play the store and send the order:
curl -i -XPOST localhost:8080/ordenes \
-H 'Content-Type: application/json' \
-d @../../../datos/ordenes/orden-1001.json
curlis a program that makes HTTP requests from the terminal.-ishows you the code and the headers of the response, not only the body.-XPOSTis the method.-Hadds a header.-d @archivosends that file as the body.
Look at the two terminals. In the route's terminal you see Recibí la orden 1001 and La API contestó …. Now ask
the API what it stored; it lives on port 8081:
curl localhost:8081/pedidos/1001
5. Compare with your prediction
Send the same order a second time and notice the code. Then try an order with no order lines: copy the order,
change its number ("orden": "1002", so that it is a new order), leave the order lines empty and send it.
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
| Case | What the API answers | What it means |
|---|---|---|
| First time | 201 | Created: "I created it" |
| The same order again | 200, with ya_existia |
"I already had it; I did not duplicate it". The API recognized the key |
| No order lines | 422 | "I understood what you sent, but it makes no sense": an order with no line items cannot be recorded |
Without the Idempotency-Key key |
400 | "You are missing something mandatory" |
| The same key with different content | 422 | "You already used this key with something different". Look at the type in the body |
This table is the contract of the course's API. From the IETF draft for Idempotency-Key it takes the 400 without
a key and the 422 for a reused key; the 201 and the 200 are decided by this API, because the draft does not fix them.
And one more difference: in the draft the key is a quoted string ("1001"); here it goes without quotes, just like the
order number. An API that followed the draft to the letter would ask for it in quotes: before integrating, you read
its contract.
When something goes wrong, the API answers with an error JSON in a standard shape (Problem Details, the type
application/problem+json): it carries type, title, status and detail. The type is what tells one 422 from another.
You did not try the last two. How would you go about causing a 400? Hint: which line of the route sets the key? And what if you send order 1001 with a different quantity? It answers 422, the same as the order with no order lines. How do you tell the two apart? Look at the body of the response. Run the tests and then put the route back the way it was.
Do you see why the order with no order lines needed a different number? With 1001 you would have had the same key with different content, and the 422 would have been because of the key, not because of the order lines.
What matters about the 200: if the network fails and the store resends the order, the API does not create two orders, because the key tells it that it is the same one. That is why the order's id travels from the first station. In lesson 18 you will build that same protection into your own integration.
6. Check
Stop the route with Ctrl+C (otherwise port 8080 stays taken) and, from the lesson folder:
cd ..
./verifica
verifica restarts the API so that it starts empty, starts your route, sends the order twice and checks. It is done
when you see the five green checks:
✅ 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
The last one is confirmed by the API, not by your route: verifica reads what the destination wrote down. Your
route saying that it sent something does not prove that it arrived; whoever received it proves it. That idea will come
back many times in the course.
Not working? ./verifica solucion tests ours. If ours comes out green and yours does not,
diff mio/orden-a-api.camel.yaml solucion/orden-a-api.camel.yaml tells you where they differ.
| What you see | What to do |
|---|---|
El puerto 8080 está ocupado |
A route was left running in another terminal: stop it with Ctrl+C |
La API no levantó: ¿corriste la 00? |
Turn on the environment: docker compose -f infra/compose.yaml up -d --wait |
curl: (7) Failed to connect |
The route has not started yet: wait for the Started line |
Why it was done this way
What we decided in this lesson, along with what we ruled out and what would make us change our mind:
- The API receives an idempotency key
Review
- Which is the input station of this route, and which is the output one?
- What is the
Idempotency-Keyheader for, and where does its value come from? - What is the difference between a 201 and a 200 in this API?
- Why does the route call
api-pedidosand not an IP address? - Why is the last check made by the API and not by your route?
Next: in lesson 03 the translator no longer comes ready-made. You write it yourself, and some test cases tell you whether it came out right.
Prefer email? Write to us at hola@habil.mx