Інтэрфейс

REST API кнігі

Апісанне збіраецца з тых самых наладаў, з якіх працуе сам інтэрфейс.

Гэтая старонка не вычытана носьбітам мовы, на якой вы яе чытаеце. Галіновыя тэрміны могуць быць перададзены недакладна; лічбы і крыніцы пад імі аднолькавыя на ўсіх мовах.

У кнігі два інтэрфейсы паверх адной мадэлі: REST і GraphQL. Апісанне ніжэй сабрана з тых самых калекцый, з якіх пабудаваны сам API, і абнаўляецца разам з імі — разыходзіцца ім няма дзе. Машыннае апісанне ляжыць па адрасе /api-docs/openapi.json у фармаце OpenAPI 3.1: яго прымаюць 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. Гэта тая ж мадэль і тыя ж правілы доступу, іншы спосаб пытацца: за адзін запыт можна ўзяць жывёлу разам з ацёламі і радаводам, не збіраючы яе з трох зваротаў.