Към съдържанието
Съдържание на курса

Урок 02 — Поръчката стига до API-то

От · съосновател и 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-то получава ключ за идемпотентност

Преговор

  1. Коя е входната гара на този маршрут и коя — изходната?
  2. За какво служи хедърът Idempotency-Key и откъде идва стойността му?
  3. Каква е разликата между 201 и 200 в този API?
  4. Защо маршрутът вика api-pedidos, а не IP адрес?
  5. Защо последната проверка я прави API-то, а не твоят маршрут?

Следва: в урок 03 преводачът вече не идва готов. Пишеш го ти, а няколко тестови случая ти казват дали се е получил.

Да обсъдим вашия проект

Предпочитате имейл? Пишете ни на hola@habil.mx