Հիմնական հասկացություններ

JSON:API-ն ունի բազմաթիվ հասկացություններ իր սպեցիֆիկացիայում, որոնք բոլորն այստեղ չեն փաստաթղթավորվել։ Սակայն մոդուլի օգտագործողները պարտադիր չէ ամբողջությամբ հասկանան բոլոր կոնցեպտները արդյունավետ աշխատելու համար։ Եթե դուք ցանկանում եք ավելի խորությամբ ուսումնասիրել, թե ինչպես է կառուցված JSON:API փաստաթուղթը, ինչու մոդուլը ինչ-որ բան այսպես է անում, կամ պարզապես ցանկանում եք ավելին իմանալ մոդուլի դիզայնի մասին, խորհուրդ է տրվում կարդալ սպեցիֆիկացիան՝ jsonapi.org կայքում։

Փաստաթղթի կառուցվածք

JSON:API-ն շատ հստակ է այն հարցում, թե ինչպես պետք է կառուցված լինեն JSON փաստաթղթերը և ինչ ինֆորմացիա պետք է լինի յուրաքանչյուր հարցման և/կամ պատասխանի մեջ։

Յուրաքանչյուր հարցման/պատասխանի մարմինը պետք է լինի մեկ ընդհանուր JSON օբյեկտի տակ։

{
   // այստեղ ձեր տվյալներն են...
}

Տվյալները կամ ռեսուրսներին վերաբերող ինֆորմացիան պետք է լինի այս վերին մակարդակի օբյեկտում data «անդամի» տակ։ «Անդամ» այստեղ նշանակում է նախապես սահմանված բանալի JSON օբյեկտում։ data անդամը կարող է լինել կամ օբյեկտ ({}), կամ զանգված ([])։ Երբ ստեղծում կամ թարմացնում եք ռեսուրս, դա միշտ կլինի օբյեկտ ({})՝ ներկայացնելով միայն մեկ տարր։ Միայն երբ ստանում եք «հավաքածու» (բազմաթիվ ռեսուրսներ), այդ հատկությունը կլինի զանգված։

{
  "data": {
    // Այստեղ ձեր ռեսուրսի տվյալներն են։
  }
}

Այլ վերին մակարդակի անդամներ են՝ errors, meta, links և included։ Դրանցից included-ը հաճախ է օգտագործվում, բայց դա կբացատրվի հետագա փաստաթղթում։

Վերին մակարդակի կառուցվածքի մասին ավելի շատ մանրամասների համար կարող եք դիմել սպեցիֆիկացիային։

data և included անդամներում կան «ռեսուրսի օբյեկտներ» կամ «ռեսուրսի նույնականացուցիչ օբյեկտներ»։ «Ռեսուրսի օբյեկտները» ներկայացնում են այն ռեսուրսների (էակների) պարունակությունը, որոնցով դուք զբաղվում եք։ «Ռեսուրսի նույնականացուցիչ օբյեկտները» նման են տվյալների բազայի արտաքին բանալիներին (foreign keys)․ դրանք նույնականացնում են ռեսուրսը՝ առանց այդ ռեսուրսի դաշտերը պարունակելու։ Drupal-ի դեպքում, ռեսուրսի օբյեկտը սովորաբար մեկ էակի (օրինակ՝ node, taxonomy term, user) JSON ներկայացումն է։ Ռեսուրսի նույնականացուցիչը բավական է էակը բեռնելու համար՝ տիպ և ID։

Յուրաքանչյուր ռեսուրսի օբյեկտ պարտադիր է պարունակի երկու անդամ՝ type և id։ Միակ բացառությունը՝ երբ ստեղծում եք նոր էակ, այդ դեպքում id-ը կարելի է բաց թողնել, որպեսզի Drupal-ը գեներացնի նոր ID։ Սակայն հաճախորդային հավելվածը նույնպես կարող է տրամադրել UUID նոր էակի համար։ Բոլոր ID-ները JSON:API-ում UUID-ներ են։

type անդամը միշտ պարտադիր է։ type-ի արժեքը գրվում է էակի տիպի և bundle-ի անունից (եթե կա)։ Էակի ռեսուրսի տիպը միշտ հետևում է entity_type--bundle ձևաչափին։ Օրինակ՝ հիմնական article և basic page node-երը կներկայացվեն որպես node--article և node--page։

Այսպիսով, եթե էակը չունի պարտադիր դաշտեր, կարելի է ստեղծել նոր էակ այս JSON-ով՝

{
  "data": {
    "type": "node--my-bundle",
  }
}

Սակայն սա շատ օգտակար չի լինի։ Պետք է ավելացնել իրական արժեքներ էակի համար։ Դրա համար JSON:API-ն ունի երկու անդամ արժեքների համար՝ attributes և relationships։ attributes-ը պահում է հիմնական ռեսուրսին վերաբերող արժեքները։ relationships-ը պահում է մյուս ռեսուրսներին պատկանող արժեքները։ Drupal-ում relationships-ը սովորաբար ներկայացնում է էակի հղման դաշտ։ Օրինակ՝ core article bundle-ում դա կարող է լինել uid դաշտը, քանի որ uid-ը հոդվածի հեղինակի օգտատիրոջ էակի հղում է։ Փաստաթղթի մարմինը attributes և relationships հետ կարող է այսպիսին լինել՝

{
  "data": {
    "type": "node--my-bundle",
    "id": "2ee9f0ef-1b25-4bbe-a00f-8649c68b1f7e",
    "attributes": {
      "title": "An Example"
    },
    "relationships": {
      "uid": {
        "data": {
          "type": "user--user",
          "id": "53bb14cc-544a-4cf2-88e8-e9cdd0b6948f"
        }
      }
    }
  }
}

Ինչպես տեսնում եք, uid դաշտը գտնվում է relationships անդամի տակ։ Ինչպես հիմնական ռեսուրսի դեպքում, այն նույնպես ունի type և id անդամներ, քանի որ դա առանձին ռեսուրս է։

Նկատեք, որ uid-ը չունի attributes կամ relationships։ Դա այն պատճառով է, որ JSON:API-ն չի ներառում հարաբերության պարունակությունը, եթե դա հատուկ չի պահանջվում include հարցման պարամետրով։ Այդ մասին ավելի մանրամասն՝ հետագա փաստաթղթում («Ռեսուրսների ստացում (GET)» բաժնում)։

Ռեսուրսի օբյեկտների կառուցվածքի մասին ավելի շատ մանրամասների համար կարող եք դիմել սպեցիֆիկացիային։

§ «Վիրտուալ» ռեսուրսի նույնականացուցիչներ

Որոշ դեպքերում, Drupal-ը թույլ է տալիս հարաբերությանը հղում տալ ռեսուրսի (էակին), որը պահված չէ տվյալների բազայում և հետևաբար անհասանելի է JSON:API-ով։ «Վիրտուալ» ռեսուրսի նույնականացուցիչը կարող է տարբեր բաներ նշանակել ըստ համատեքստի, սակայն միշտ վերաբերում է ռեսուրսի, որը հնարավոր չէ գտնել։

Վիրտուալ ռեսուրսի նույնականացուցիչի օգտագործումը և նշանակությունը Drupal core-ում

Taxonomy term-ի parent դաշտը ամենահետաքրքիր օրինակն է Drupal core-ում այս դեպքի համար։ Այս հարաբերության դաշտը կարող է պարունակել ռեսուրսի նույնականացուցիչ «վիրտուալ» taxonomy term ռեսուրսի համար։ Այս դեպքում, «վիրտուալ» նույնականացուցիչը համապատասխանում է <root> taxonomy term-ին։ Սա նշանակում է, որ հղվող term-ը իր բառարանի ամենավերին մակարդակում է։

Դիտեք հետևյալ պատասխանի օրինակային փաստաթուղթը՝

{
  "data": {
    "type": "taxonomy_term--tags",
    "id": "2ee9f0ef-1b25-4bbe-a00f-8649c68b1f7e",
    "attributes": {
      "name": "Politics"
    },
    "relationships": {
      "parent": {
        "data": [
          {
            "id": "virtual",
            "type": "taxonomy_term--tags",
            "meta": {
              "links": {
                "help": {
                  "href": "https://www.drupal.org/docs/8/modules/json-api/core-concepts#virtual",
                  "meta": {
                    "about": "Վիրտուալ ռեսուրսի նույնականացուցիչի նշանակությունը և օգտագործումը։"
                  }
                }
              }
            }
          }
        ]
      }
    }
  }
}

Նկատեք, որ այս Term-ի parent հարաբերության (էակի հղման դաշտ) նույնականացուցիչ օբյեկտի id-ը UUID չէ, այլ "virtual"։ Սա անհրաժեշտ է, որովհետև ամենավերին մակարդակի կամ root-level Term-ը ունի հղում դեպի չպահվող <root> term (target_id = 0) որպես ծնող։

Ինչո՞ւ։

Քանի որ արմատային term-ը պահված չէ, և Term-ը կարող է մեկից ավելի ծնող ունենալ, կարևոր հարցն այն է, թե ինչպես տարբերակել՝ Term-ը՝

• ունենում է միայն Term 3-ը որպես ծնող ([3])?
• ունի և՛ չպահվող արմատային Term-ը, և Term 3-ը որպես ծնող ([0, 3])?

Պատասխանը հետևյալն է․ եթե JSON:API-ն բաց թողներ չպահվող արմատային term 0-ը ու չօգտագործեր "virtual" ID, այդ դեպքում հնարավոր չէր տարբերակել այս երկու դեպքերը։

§ «Բացակայող» ռեսուրսի նույնականացուցիչներ

Drupal-ը չի «մաքրում» հարաբերությունները դեպի ջնջված ռեսուրսներ (էակի հղման դաշտերը կարող են պահել հղումներ դեպի ջնջված էակներ)։ Այսինքն՝ Drupal-ը թողնում է «կախված» հարաբերություններ։

Երբ JSON:API-ն հանդիպում է այդպիսի կախված հարաբերությունների, օգտագործում է «բացակայող» ռեսուրսի նույնականացուցիչ։

Բացակայող ռեսուրսի նույնականացուցիչի օգտագործումը և նշանակությունը Drupal core-ում

Մնալով վիրտուալ նույնականացուցիչի օրինակին՝ taxonomy term-ի parent դաշտում։ Պատկերացրեք, որ որոշակի տաքսոնոմիայի տերմին ժամանակին ուներ «Բելգիա» տաքսոնոմիայի տերմինը որպես ծնող, սակայն հիմա «Բելգիա»-ի տերմինը այլևս գոյություն չունի։ Այդ դեպքում այս հարաբերության դաշտը կպարունակի «բացակայող» տաքսոնոմիայի տերմինի նույնականացուցիչ։

Օրինակային պատասխան՝

{
  "data": {
    "type": "taxonomy_term--tags",
    "id": "2ee9f0ef-1b25-4bbe-a00f-8649c68b1f7e",
    "attributes": {
      "name": "Politics"
    },
    "relationships": {
      "parent": {
        "data": [
          {
            "id": "missing",
            "type": "unknown",
            "meta": {
              "links": {
                "help": {
                  "href": "https://www.drupal.org/docs/8/modules/json-api/core-concepts#missing",
                  "meta": {
                    "about": "Բացակայող ռեսուրսի նույնականացուցիչի նշանակությունը և օգտագործումը։"
                  }
                }
              }
            }
          }
        ]
      }
    }
  }
}

Նկատեք, որ այս Term-ի parent հարաբերության (էակի հղման դաշտ) նույնականացուցիչ օբյեկտի id-ը UUID չէ, այլ "missing" է։ Բացի այդ, type-ը unknown է (քանի որ Drupal-ը չի պահում հղված էակի bundle-ը, միայն էակի տիպը, հետևաբար JSON:API ռեսուրսի տիպի անունը որոշել հնարավոր չէ)։

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