Интерфейс

Китептин 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. Бул — ошол эле модель жана ошол эле жеткиликтүүлүк эрежелери, суроонун башка ыкмасы: бир суроо менен малды тууттары жана санжырасы менен бирге алууга болот, аны үч кайрылуудан чогултпастан.