Տերմինների բառարան

Կարճ տարբերակ (TL;DR)՝

• HTTP հարցումները կատարվում են JSON:API ռեսուրսների։ Չշփոթեք դրանք ռեսուրսի օբյեկտների հետ։
• Հաճախորդին փոխանցվող JSON օբյեկտը կոչվում է փաստաթուղթ (document):
• Փաստաթուղթը միշտ JSON օբյեկտ է և ունի հիմնական տվյալներ data բանալու տակ։
• Այդ բանալիի տակ գտնվող տվյալները կոչվում են ռեսուրսի օբյեկտներ կամ ռեսուրսի նույնականացուցիչ օբյեկտներ։
• Երբ խնդրում եք, որ հարակից տվյալները տեղադրվեն փաստաթղթում, այն դառնում է բաղադրյալ փաստաթուղթ (compound document):
• Բաղադրյալ փաստաթուղթն ունի included բանալի վերին մակարդակի օբյեկտում։
• Ռեսուրսները, որոնք վերադարձնում են շատ ռեսուրսի օբյեկտներ, կոչվում են հավաքածուի ռեսուրսներ։
• Ռեսուրսները, որոնք վերադարձնում են մեկ ռեսուրսի օբյեկտ, կոչվում են առանձին ռեսուրսներ։
• Ռեսուրսները, որոնք վերադարձնում են ինֆորմացիա ռեսուրսի օբյեկտների միջև կապերի մասին, կոչվում են կապի ռեսուրսներ։
• Drupal-ի տերմիններով՝
  • Ռեսուրսի օբյեկտներ → Էակներ (Entities)
  • Ռեսուրսի նույնականացուցիչ օբյեկտներ → Էակի հղման դաշտի տարրեր (Entity reference field Items)
  • Փաստաթուղթ → Հարցման/պատասխանի JSON բեռնվածք

Ստորև ներկայացված է հակիրճ նկարագրություն այն տերմինների և հասկացությունների, որոնք օգտագործվում են JSON:API մոդուլը նկարագրելիս։

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

Այս սահմանումներից շատերը փոխկապակցված են։ Այս էջի վերջում կա սխեմա, որտեղ տերմինները ներկայացված են իրենց համատեքստում։

Ռեսուրս (Resource)

Վայր, որտեղ կարելի է ստանալ JSON:API պատասխանի փաստաթուղթ։ Ռեսուրսը գտնում են իր URL-ով (համընդհանուր ռեսուրսի դիրքորոշիչով)։ Այն չպետք է շփոթել «ռեսուրսի օբյեկտի» հետ։ Ռեսուրսը չունի մեկ-մեկին համապատասխանություն հավելվածի տվյալների հետ։

Drupal-ի դեպքում՝ JSON:API ռեսուրսը համարժեք չէ էակի։ Փոխարենը, ռեսուրսը տվյալներ ստանալու վայր է որևէ կոնցեպտի համար։ Օրինակ՝ այդ կոնցեպտը կարող է լինել «node--article տիպի ռեսուրսի օբյեկտների հավաքածու» կամ «որոշակի հոդված node-ի field_tags էակի հղման դաշտի ներկայացում»։

Պատասխանի փաստաթուղթ (Response Document)

JSON-ով կոդավորված պատասխան մարմին, որն վերադարձվում է JSON:API ռեսուրսից։ Սա «ծրարի» (envelope) պես է, որտեղ տվյալներն ու սխալներն են հաղորդվում HTTP հաճախորդին։ Երբ փաստաթուղթն ունի included անդամ, այն կոչվում է բաղադրյալ փաստաթուղթ։

Բաղադրյալ փաստաթուղթ (Compound Document)

Պատասխանի փաստաթուղթ, որն ունի included անդամ։ Բաղադրյալ փաստաթուղթը թույլ է տալիս մեկ հարցմամբ ստանալ հարակից ռեսուրսի օբյեկտները՝ տեղադրելով դրանք հիմնական տվյալների կողքին։ Դա կարելի է անել include հարցման պարամետրով։

Սխալի փաստաթուղթ (Error Document)

Պատասխանի փաստաթուղթ, որն ունի errors անդամ, որը պարունակում է մեկ կամ ավելի սխալի օբյեկտներ։ Երբեք չի ունենա data անդամ։ Պատասխանի HTTP կարգավիճակի կոդը կլինի 4xx կամ 5xx մակարդակի։

Առանձին ռեսուրս (Individual Resource)

Ռեսուրս, որը data անդամի տակ ունի մեկ ռեսուրսի օբյեկտ։ Բավարար իրավասության դեպքում այն ընթեռնելի և փոփոխելի է։ Drupal-ում այն կարելի է օգտագործել էակը դիտելու, թարմացնելու կամ ջնջելու համար։ Չի կարող օգտագործվել էակ ստեղծելու համար։

Հավաքածուի ռեսուրս (Collection Resource)

Ռեսուրս, որի data անդամի տակ կա շատ ռեսուրսի օբյեկտներ։ Բավարար իրավասության դեպքում ընթեռնելի և գրելի է։ Այս ռեսուրսները կարող են էջավորվել, զտվել և դասավորվել։ Drupal-ում՝ կարող է օգտագործվել նոր էակ ստեղծելու համար։ Չի կարող օգտագործվել հավաքածուի էակները թարմացնելու կամ ջնջելու համար։

Կապի ռեսուրս (Relationship Resource)

Ռեսուրս, որի վերին մակարդակի օբյեկտն է կապի օբյեկտը։ Այն պարունակում է մեկ կամ ավելի ռեսուրսի նույնականացուցիչ օբյեկտներ, որոնք յուրաքանչյուրն ներկայացնում է հղում մեկ ռեսուրսի օբյեկտից մյուսին։ Բավարար իրավասության դեպքում ընթեռնելի և փոփոխելի է։ Drupal-ում սա օգտագործվում է մեկ էակի հղման դաշտի տարրերը դիտելու կամ խմբագրելու համար։

Կապակցված ռեսուրս (Related Resource)

Ռեսուրս, որը հատուկ հավաքածուի ռեսուրս է, պարունակում է մեկ կամ ավելի ռեսուրսի օբյեկտներ data անդամի տակ։ Այս ռեսուրսի օբյեկտները հարաբերության առարկաներն են։ Այս ռեսուրսը միայն ընթեռնելի է։ Drupal-ում այն օգտագործվում է այն էակները դիտելու համար, որոնք հղված են էակի հղման դաշտով, բայց հնարավոր չէ խմբագրել այդ դաշտը կամ թարմացնել այդ էակները։

Փաստաթղթի անդամ (Document member)

JSON օբյեկտ, որը վերին մակարդակի JSON:API փաստաթղթի մաս է։ Դրանք միշտ գտնվում են փաստաթղթում՝ սպեցիֆիկացիայով սահմանված բանալիների տակ (օր. jsonapi, data, included կամ errors)։

Ռեսուրսի օբյեկտ (Resource Object)

Էակի ներկայացում որպես JSON օբյեկտ։ Չպետք է շփոթել «ռեսուրսի» հետ։ Սա ունի մեկ-մեկին համապատասխանություն հավելվածի տվյալների հետ։

Ատրիբուտների օբյեկտ (Attributes Object)

JSON օբյեկտ, որը ներկայացնում է ռեսուրսի օբյեկտի ինֆորմացիան։ Ատրիբուտները կարող են լինել ցանկացած վավեր JSON արժեք։ Drupal-ում սա ներկայացնում է բոլոր այն դաշտերի արժեքները, որոնք էակի հղում չեն։

Կապերի օբյեկտ (Relationships Object)

JSON օբյեկտ, որը պարունակում է ռեսուրսի օբյեկտի հղումները դեպի այլ ռեսուրսի օբյեկտներ։ Այն պարունակում է բազմաթիվ անդամներ, որոնք կապի օբյեկտներ են (ենթաբաժիններ)։ Drupal-ում դա ներկայացնում է բոլոր էակի հղման դաշտերի արժեքները։

Կապի օբյեկտ (Relationship Object)

JSON օբյեկտ, որը ներկայացնում է ռեսուրսի օբյեկտի հղումները դեպի այլ ռեսուրսի օբյեկտներ։ Այն պարունակում է ռեսուրսի նույնականացուցիչ օբյեկտներ, որոնցից յուրաքանչյուրը ներկայացնում է մեկ հղում այլ ռեսուրսի օբյեկտի։ Drupal-ում սա ներկայացնում է մեկ էակի հղման դաշտ։

Ռեսուրսի նույնականացուցիչ օբյեկտ (Resource Identifier Object)

Շատ պարզ JSON օ