Интерфейс

Кітаптың REST API-і

Сипаттама интерфейстің өзі жұмыс істейтін баптаулардан жиналады: олардың арасы ажырамайды.

Бұл бетті сіз оқып отырған тілдің иесі тексерген жоқ. Сала терминдері дәл берілмеуі мүмкін; сандар мен олардың астындағы дереккөздер барлық тілде бірдей.

Кітапта бір модельдің үстінде екі интерфейс бар: REST және GraphQL. Төмендегі сипаттама API-дің өзі құрылған сол коллекциялардан жиналады және олармен бірге жаңарады — олардың арасы ажырамайды. Машиналық сипаттама OpenAPI 3.1 форматында мына мекенжайда жатыр: /api-docs/openapi.json — оны Postman, Insomnia және клиент генераторлары қабылдайды.

Қалай кіру керек

POST /api/users/login пошта мен құпиясөзбен токен қайтарады. Әрі қарай ол сұрау тақырыбында беріледі:

Authorization: JWT <токен>

Браузерге оңайырақ: сол сұрау нүктесі cookie қояды, әрі қарай ол онымен өзі жүреді.

Неге жауаптар әртүрлі

Бір сұрау нүктесі әркімге әртүрлі береді: шаруашылық өз жазбаларын және ашықтарын көреді, Қауымдастық — барлығын, аноним — тек ашықтарын. Бұл — қолжетімділік ережелері, жауаптың схемасы емес, және оларды сипаттамада білдіру мүмкін емес.

Бос нәтиже «бұл жоқ» дегеннен гөрі «бұл сізге көрінбейді» дегенді жиі білдіреді.

Іріктеу

Шарттар кірістірілген параметрлермен беріледі:

?where[state][equals]=alive
&where[birthDate][greater_than]=2020-01-01

OpenAPI-дің стандартты құралдарымен бұл тіл сипатталмайды — спецификацияда ол жол деп жарияланған, бар болғанынан дәлірек көрінбеу үшін.

Неден бастау керек

Бізге ең жиі келетін үш міндет. Әрі қарай анықтамалық: онда тоқсанға жуық сұрау нүктесі бар, және ол не іздеп жүргенін білетін адамға жауап береді.

1. Кіру және токен алу

Қалғанының бәрі содан басталады: токенсіз сұрау нүктелері тек ашығын береді.

BASE=https://…

curl -X POST \
  "$BASE/api/users/login" \
  -H content-type:application/json \
  -d '{"email":"…","password":"…"}'

BASE — осы жүйенің мекенжайы. Жауапта token өрісі бар, жарамдылық мерзімі — exp өрісінде.

2. Өз табыныңды жүктеп алу

Шартта иесін атаудың қажеті жоқ: нәтиже онсыз да сіздің шаруашылығыңызбен шектелген — сұрау параметрімен емес, қолжетімділік ережелерімен.

curl "$BASE/api/animals\
?where[archived][not_equals]=true\
&limit=200&depth=0" \
  -H "Authorization: JWT $TOKEN"

depth=0 байланыстарды идентификаторлармен береді — байланысты жазбалардың өзі керек болмаса, жылдамырақ әрі болжамдырақ.

3. Бақылау сауымын жазу

API-ді көбіне дәл сол үшін қосады: сауымдар ай сайын және мыңдаған жолмен келеді.

curl "$BASE/api/milk-tests" \
  -H "Authorization: JWT $TOKEN" \
  -H content-type:application/json \
  -d '{"animal":123,
      "date":"2026-08-01",
      "milkYield":28.4}'

Тек өз шаруашылығының малын жазуға болады — бұл формада емес, серверде тексеріледі.

Мысалдарда қойылатын екі мән бар: $BASE — осы бет ашылған мекенжай, және $TOKEN — кіру қайтарған нәрсе. Төмендегі анықтамалықта ештеңе қоюдың қажеті жоқ: ондағы мекенжай онсыз да біздікі, ал токен авторизация түймесімен бір рет енгізіледі.

Загружаем справочник…

REST-пен қатар GraphQL жұмыс істейді — /api/graphql. Бұл — сол модель және сол қолжетімділік ережелері, сұраудың басқа тәсілі: бір сұраумен малды бұзаулауларымен және шежіресімен бірге алуға болады, оны үш өтініштен жинамай.