Съдържание на курса
Урок 02 — Поръчката стига до API-то
От Dorian Chávez · съосновател и Chief Executive Officer на Hábil ·
Какво ще постигнеш: една поръчка от магазина да влезе в твоя маршрут през интернет и да стигне до API-то за поръчки, и да разбереш какво отговаря API-то във всеки случай. За първи път твоята интеграция говори с друга система.
Преди да започнеш, ти трябват: завършен урок 01 и включена средата от урок 00:
docker compose -f infra/compose.yaml up -d --wait # desde la carpeta raíz de la práctica
Новото днес, в едно изречение
В урок 01 входната гара беше папка. Днес тя е HTTP адрес: магазинът праща поръчката така, както браузърът ти праща формуляр, а твоят маршрут я препраща към API-то за поръчки по същия начин.
HTTP, най-необходимото: една програма праща на друга заявка с метод (POST значи „ето ти нещо ново“),
адрес (/ordenes), няколко хедъра (данни за съобщението, като етикети върху плик) и тяло
(поръчката). Другата отговаря с трицифрен код и със собствено тяло. Ако искаш повече, виж картата в
conceptos/antes-de-empezar/.
1. Подготви папката си
cd lecciones/02-la-orden-llega-a-la-api
cp -R inicio mio
cd mio
2. Прочети маршрута
Отвори orden-a-api.camel.yaml. Има пет стъпки:
POST /ordenes → sacar el id de la orden → traducir → POST a la API → anotar lo que contestó
| Стъпка в YAML-а | Какво прави |
|---|---|
from: platform-http:/ordenes с httpMethodRestrict: POST |
Входната гара. Отваря адреса /ordenes; параметърът httpMethodRestrict прави така, че да приема само POST. Порт 8080 не го задава маршрутът: отваря го herramientas/camel |
setHeader с name: Idempotency-Key и израза jsonpath "$.orden" |
Взема номера на поръчката ("orden": "1001") и го слага в хедър с име Idempotency-Key. Това е ключът, по който API-то разпознава поръчка, която вече е получило |
to: jsonata:…/mapeo.jsonata |
Превежда поръчката от формата на магазина във формата на API-то. Преводачът вече е готов; в урок 03 го пишеш ти |
removeHeaders: CamelHttp* |
Изтрива етикетите на входящото извикване, за да не се смесят с тези на изходящото |
to: http://api-pedidos:8080/pedidos |
Изходната гара. Вика API-то по името на услугата (api-pedidos), а не по IP номер |
Отвори също datos/ordenes/orden-1001.json и mio/mappings/api/pedido/v1/mapeo.jsonata. Сложи ги един до друг:
кое име се е променило (renglones → ?) и кое е останало същото?
3. Предвиди
API-то за поръчки не приема каквото и да е: отговаря с различен код според това, което му пристигне. Преди да пуснеш маршрута, запиши на лист хартия какъв код според теб връща във всеки случай:
| Случай | Твоето предвиждане |
|---|---|
| Пращаш поръчка 1001 за първи път | |
| Пращаш същата поръчка 1001 още веднъж | |
| Пращаш поръчка без редове |
4. Пусни го и му прати една поръчка
В един терминал стартирай маршрута:
../../../herramientas/camel run orden-a-api.camel.yaml
Първия път се бави повече, защото Camel сваля това, което му трябва, за да говори HTTP. Изчакай реда
Started orden-a-api.
В друг терминал, от същата папка mio/, влез в ролята на магазина и прати поръчката:
curl -i -XPOST localhost:8080/ordenes \
-H 'Content-Type: application/json' \
-d @../../../datos/ordenes/orden-1001.json
curlе програма, която прави HTTP заявки от терминала.-iти показва кода и хедърите на отговора, а не само тялото.-XPOSTе методът.-Hдобавя хедър.-d @archivoпраща този файл като тяло.
Погледни двата терминала. В този на маршрута се появяват Recibí la orden 1001 и La API contestó …. Сега попитай
API-то какво е записало; то живее на порт 8081:
curl localhost:8081/pedidos/1001
5. Сравни с предвиждането си
Прати същата поръчка втори път и обърни внимание на кода. После опитай с поръчка без редове: копирай поръчката,
смени ѝ номера ("orden": "1002", за да е нова поръчка), остави редовете празни и я прати.
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
| Случай | Какво отговаря API-то | Какво означава |
|---|---|---|
| Първи път | 201 | Created: „създадох я“ |
| Същата поръчка още веднъж | 200, с ya_existia |
„Вече я имах; не я дублирах“. API-то е разпознало ключа |
| Без редове | 422 | „Разбрах какво ми прати, но няма смисъл“: поръчка без позиции не може да се регистрира |
Без ключа Idempotency-Key |
400 | „Липсва ти нещо задължително“ |
| Същият ключ с друго съдържание | 422 | „Този ключ вече го използва с нещо различно“. Виж type в тялото |
Тази таблица е договорът на API-то в курса. От черновата на IETF за Idempotency-Key той взема 400 без
ключ и 422 при повторно използван ключ; 201 и 200 ги решава този API, защото черновата не ги определя. И още една
разлика: в черновата ключът е низ в кавички ("1001"); тук е без кавички, също като номера
на поръчката. API, който следва черновата буквално, би го искал в кавички: преди да интегрираш, се чете
договорът му.
Когато нещо се обърка, API-то отговаря с JSON за грешка в стандартна форма (Problem Details, типът
application/problem+json): носи type, title, status и detail. Именно type отличава един 422 от друг.
Последните два случая не ги пробва. Как би предизвикал 400? Подсказка: кой ред от маршрута слага ключа? А ако пратиш поръчка 1001 с друго количество? Отговаря ти 422, също както при поръчката без редове. Как различаваш двата? Виж тялото на отговора. Направи опитите и после върни маршрута както си беше.
Виждаш ли защо поръчката без редове имаше нужда от друг номер? С 1001 щеше да имаш същия ключ с друго съдържание и 422 щеше да е заради ключа, а не заради редовете.
Важното при 200: ако мрежата откаже и магазинът прати поръчката отново, API-то не създава две поръчки, защото ключът му казва, че е същата. Затова идентификаторът на поръчката пътува още от първата гара. В урок 18 ще построиш същата защита в собствената си интеграция.
6. Провери
Спри маршрута с Ctrl+C (иначе порт 8080 остава зает) и от папката на урока:
cd ..
./verifica
verifica рестартира API-то, за да започне празно, стартира твоя маршрут, праща поръчката два пъти и проверява. Урокът е завършен,
когато видиш петте зелени отметки:
✅ 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
Последната я потвърждава API-то, не твоят маршрут: verifica чете какво е записала дестинацията. Това, че маршрутът ти казва, че е пратил нещо,
не доказва, че то е пристигнало; доказва го този, който го е получил. Тази идея ще се връща много пъти в курса.
Не тръгва? ./verifica solucion тества нашето решение. Ако нашето излиза в зелено, а твоето — не,
diff mio/orden-a-api.camel.yaml solucion/orden-a-api.camel.yaml ти казва по какво се различават.
| Какво виждаш | Какво правиш |
|---|---|
El puerto 8080 está ocupado |
Останал е работещ маршрут в друг терминал: спри го с Ctrl+C |
La API no levantó: ¿corriste la 00? |
Включи средата: docker compose -f infra/compose.yaml up -d --wait |
curl: (7) Failed to connect |
Маршрутът още не е стартирал: изчакай реда Started |
Защо е направено така
Какво решихме в този урок, заедно с това, което отхвърлихме, и какво би ни накарало да си променим мнението:
- API-то получава ключ за идемпотентност
Преговор
- Коя е входната гара на този маршрут и коя — изходната?
- За какво служи хедърът
Idempotency-Keyи откъде идва стойността му? - Каква е разликата между 201 и 200 в този API?
- Защо маршрутът вика
api-pedidos, а не IP адрес? - Защо последната проверка я прави API-то, а не твоят маршрут?
Следва: в урок 03 преводачът вече не идва готов. Пишеш го ти, а няколко тестови случая ти казват дали се е получил.
Предпочитате имейл? Пишете ни на hola@habil.mx