Ինտերֆեյս

Մատյանի 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. Սա նույն մոդելն է և հասանելիության նույն կանոնները, հարցնելու այլ եղանակ. մեկ հարցումով կարելի է վերցնել կենդանուն իր ծինների և տոհմածառի հետ միասին՝ առանց այն երեք դիմումից հավաքելու։