JSON:API ներքին համակարգ

JsonDrop API-ն օգտագործում է JSON:API իրականացում backend/frontend փոխազդեցության համար և լիովին համապատասխանում է՝

JSON:API Specification-ին։

Postman հավաքածու (collection)՝ պատրաստ վերջնակետերով (endpoints):

https://drive.google.com/file/d/1rMf0XdrK1zXwPqLQVsTH44Z2ttFxj7ss/view?usp=drive_link

JSON:API բնութագիրը իր մասին ասում է.

[Դա] բնութագիր է, թե ինչպես հաճախորդը պետք է պահանջի ռեսուրսների որոնում կամ փոփոխություն, և ինչպես սերվերը պետք է պատասխան տա այդ հարցումներին։

JSON:API-ն նախագծված է նվազեցնելու թե՛ հարցումների քանակը, և թե՛ հաճախորդների և սերվերների միջև փոխանցվող տվյալների ծավալը։ Այս արդյունավետությունը ձեռք է բերվում՝ չխախտելով ընթերցանության, ճկունության կամ հայտնաբերման ունակությունը։

Drupal-ի տվյալների կառուցվածքները՝ կոնկրետ էնթիթի տեսակները, փաթեթները (bundles) և դաշտերը, հիանալի համատեղելի են JSON:API-ի հետ։

JSON:API մոդուլը միացնելու դեպքում դուք անմիջապես ստանում եք ամբողջական REST API Drupal հավելվածի բոլոր տեսակների համար։ JSON:API-ն ուսումնասիրում է ձեր էնթիթի տեսակներն ու փաթեթները, որպեսզի դինամիկորեն տրամադրի URL-ներ, որոնց միջոցով հնարավոր է մուտք ունենալ բոլոր ռեսուրսներին՝ օգտագործելով ստանդարտ HTTP մեթոդները՝ GET, POST, PATCH և DELETE։

JSON:API մոդուլը համարվում է արտադրության համար պատրաստ "արտ коробկա"՝ այսինքն՝ շատ հստակ սահմանում է, թե որտեղ կլինեն ռեսուրսները, ինչ մեթոդներ հասանելի կլինեն դրանց համար և մնում է հասանելիության վերահսկողությունը Drupal-ի հիմանական թույլտվությունների համակարգին։ Ներկայումս կանոնակարգման էջեր (configuration pages) չկան, ինչը թույլ է տալիս API-ով ղեկավարվող Drupal հավելված սկսել շատ հեշտությամբ և արագ։

Այս փաստաթղթավորման հորիզոնական էջերը ներառում են՝

• JSON:API-ի հիմնական կոնցեպտները և ինչպես դրանք կիրառվում են Drupal-ում
• Մոդուլը տրամադրող API-ի լայնամասշտաբ նկարագիրը
• Հետաքրքրական տեղեկություններ՝ ինչպես կազմել HTTP հարցումները
• Ինչպես իրականացնել սերտիֆիկացում (authentication)
• Հաճախ հանդիպող խնդիրներ ("gotchas")
• Մասնավոր փաստաթղթավորում՝
  • Մեկ ռեսուրսի ստացում (GET)
  • Ռեսուրսների հավաքածուի ստացում (GET՝ ֆիլտրերով, էջավորմամբ և դասավորությամբ)
  • Նոր ռեսուրս ստեղծում (POST)
  • Առկա ռեսուրսի թարմացում (PATCH)
  • Առկա ռեսուրսի հեռացում (DELETE)

Եթե ունեք հատուկ հարցեր, խնդրում ենք ստեղծել աջակցման հարց JSON:API մոդուլի խնդիրների հերթում [480 խնդիր]։

JSON:API մոդուլի API-ն կենտրոնացած է Drupal-ի էնթիթի տեսակների և փաթեթների վրա։ Ամեն փաթեթ ունի իր յուրահատուկ URL ուղի, որոնք բոլորը հետևում են միօրինակ ձևաչափի։

Հիմնական Drupal REST մոդուլի տարբերությամբ, այս ուղիները չեն կարգավորվում և միացված են լռությամբ (by default)։ JSON:API-ն պարզապես ձևաչափ չէ, ինչպես JSON կամ HAL+JSON, այլ ընդգրկում է ավելի լայն կանոնների հավաքածու՝ թե ինչպես պետք է աշխատի API-ն։ Այն կարգավորում է, թե ինչ HTTP մեթոդներ պետք է ընդունվեն, ինչ պատասխանների կոդեր պետք է վերադարձվեն հատուկ իրավիճակներում, պատասխան մարմնի ձևաչափը, և ռեսուրսների միջև կապերը։ Լրացուցիչ համեմատության համար տեսեք JSON:API և հիմնական REST մոդուլի համեմատությունը։

Տիպեր

JSON:API-ում ամեն ռեսուրս պետք է ունենա համաշխարհային յուրահատուկ type հատկություն։ Drupal JSON:API-ի իրականացումը այս հատկությունը ստեղծում է էնթիթի տեսակի մեքենայական անունից և փաթեթի մեքենայական անունից։ Օրինակ՝ հոդվածները, էջերը և օգտվողները կունենան համապատասխանաբար node--article, node--pages և user--user տիպերը։ Ուշադրություն դարձրեք, որ օգտվողի էնթիթի տիպը Drupal-ում չունի փաթեթ։ Երբ էնթիթի տիպը չունի փաթեթ, էնթիթի տիպը կրկնվում է ընթեռնելիության համար։

URL-ի կառուցվածք

JSON:API URL-ը նման տեսք ունի.

GET|POST     /jsonapi/node/article
PATCH|DELETE /jsonapi/node/article/{uuid}

Ամեն ռեսուրսի տիպը պետք է ունենա յուրահատուկ URL։ Սա նշանակում է, որ API-ում առկա յուրաքանչյուր տիպը պետք է մատչելի լինի յուրահատուկ հասցեով։ Միևնույն հասցեով կարելի է մուտք ունենալ միայն մեկ ռեսուրսի տիպին։ Drupal-ի իրականացումը հետևում է հետևյալ նմուշին՝ /jsonapi/{entity_type_id}/{bundle_id}[/{entity_uuid}]։

URL-ը միշտ նախորդվում է /jsonapi նախածանցով։

Այնուհետև հաջորդում են էնթիթի տիպի և փաթեթի անվանումները՝ ուղիղ շեղումով (slash): Նշենք, որ /jsonapi/node նման URL-ը գոյություն չունի, քանի որ նա կխախտեր JSON:API պահանջը՝ մեկ URL-ից միաժամանակ մատուցելով մի քանի ռեսուրսի տիպեր։

Առկա են:
/jsonapi/node/page
/jsonapi/node/article

Առկա չեն:
/jsonapi/node

Էնթիթի տիպի և փաթեթի անվան հետ մեկտեղ կա ոչ պարտադիր ID հատված։ Միավոր ռեսուրս հասցեացնելու համար (ստանալու, թարմացնելու կամ հեռացնելու) պետք է ներառել այդ հատվածը, որը միշտ հանդիսանում է ռեսուրսի UUID։ Նոր ռեսուրս ստեղծելիս կամ ռեսուրսների հավաքածու ստանալու դեպքում ID հատվածը բացակայում է։

GET, POST
/jsonapi/node/article

PATCH, DELETE
/jsonapi/node/article/{uuid}

HTTP մեթոդներ

JSON:API-ը սահմանում է ընդունել հետևյալ HTTP մեթոդները՝ GET, POST, PATCH, DELETE։ PUT մեթոդը ներառված չէ։

• GET – տվյալների ստացում, կարող է լինել ռեսուրսի հավաքածու կամ առանձին ռեսուրս
• POST – նոր ռեսուրս ստեղծում
• PATCH – առկա ռեսուրսի թարմացում
• DELETE – առկա ռեսուրսի հեռացում

Հարցման հեդերներ (Request headers)

Օգտագործեք համապատասխան Content-Type և Accept հեդերներ։ Այստեղ ավելի մանրամասն՝ Client responsibility։

Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

Պատասխանների կոդեր

JSON:API բնութագիրը կարգավորում է նաև ընդունելի պատասխանների կոդերը։ Drupal-ի իրականացման մեջ օգտագործվում են հետևյալ կոդերը.

• 200 OK – բոլոր հաջողակ GET և PATCH հարցումների համար
• 201 Created – բոլոր հաջողակ POST հարցումների համար (պատասխանն ընդգրկում է նոր ստեղծված ռեսուրսը)
• 204 No Content – բոլոր հաջողակ DELETE հարցումների համար

Հոդվածը վերցված է Drupal փաստաթղթավորումից։