Gobierto Vocabularies / Vocabulary management
Create vocabulary
POST /api/v1/vocabularies
Allows the creation of a new vocabulary. The request must include a valid token of an authorized admin.
Headers:
Authorization:Bearer TOKENA valid token of an admin with permissions to create terms must be provided
Body
I'ts expected to be in JSON format with the following structure:
{
"data": {
"attributes": {
// ...
}
}
}
Attributes:
| Name | Mandatory | Description |
|---|---|---|
| name_translations | YES | A JSON with the different locales and the names on each locale. Available locales are es, en and ca |
| slug | YES | The element that identifies the vocabulary in the URL. Can be used as external identifier because is unique |
| terms | NO | An array with the terms of the vocabulary. The array can include the whole list of terms or a part, and new terms can be added later. |
| terms.name_translations | YES | a JSON with the different locales and the names on each locale. Available locales are es, en and ca |
| terms.description_translations | NO | a JSON with the different locales and the names on each locale. Available locales are es, en and ca |
| terms.slug | NO | a string that identifies the vocabulary and is used in the URL of the vocabulary. The value must be unique. |
| terms.level | NO | starts at zero. The level of the term. This value is calculated automatically depending on parent terms |
| terms.position | NO | by default is zero. Sets the position of the term at that level. |
| terms.external_id | NO | the identifier of the term in the external system. This attribute must be unique, as it will be used for unique identification. |
| terms.parent_id | NO | can be null or the internal identifier id or the external_id of the parent term. |
Example body request:
{
"data": {
"type": "gobierto_common-vocabularies",
"attributes": {
"name_translations": {
"en": "New vocabulary",
"es": "Nuevo vocabulario"
},
"slug": "url-slug",
"terms": [
{
"name_translations": {
"en": "New term 1",
"es": "Nuevo termino 1"
},
"description_translations": {
"en": "New term 1 desc",
"es": "Nuevo termino 1 desc"
},
"slug": "term-slug",
"position": 0,
"level": 0,
"parent_id": null,
"external_id": "E0001"
},
{
"name_translations": {
"en": "New term 1.1",
"es": "Nuevo termino 1.1"
},
"description_translations": {
"en": "New term 1.1 desc",
"es": "Nuevo termino 1.1 desc"
},
"slug": "term-slug-11",
"position": 0,
"level": 1,
"parent_id": "E0001",
"external_id": "E0001.1"
}
]
}
}
}
Response:
- If the token is invalid or the admin is not allowed to create term: JSON with
UnauthorizedorModule not allowedwith status401 Unauthorized - If the resource could be created or already existing: JSON with id and name translations of term
Response schema:
{
"data": {
"id": "328",
"type": "gobierto_common-vocabularies",
"attributes": {
"name_translations": {
"en": "New vocabulary",
"es": "Nuevo vocabulario"
},
"slug": "url-slug",
"terms": [
{
"id": 21547,
"name_translations": {
"en": "New term 1.1",
"es": "Nuevo termino 1.1"
},
"description_translations": {
"en": "New term 1.1 desc",
"es": "Nuevo termino 1.1 desc"
},
"slug": "term-slug-11",
"position": 0,
"level": 1,
"term_id": 21546,
"parent_external_id": "E0001",
"parent_id": "E0001",
"external_id": "E0001.1"
},
{
"id": 21546,
"name_translations": {
"en": "New term 1",
"es": "Nuevo termino 1"
},
"description_translations": {
"en": "New term 1 desc",
"es": "Nuevo termino 1 desc"
},
"slug": "term-slug",
"position": 0,
"level": 0,
"term_id": null,
"parent_external_id": null,
"parent_id": null,
"external_id": "E0001"
}
]
}
}
}
List vocabularies
GET /api/v1/vocabularies
List the existing vocabularies. The request must include a valid token of an authorized admin.
Headers:
Authorization:Bearer TOKENA valid token of an admin with permissions to create terms must be provided
Example of response:
{
"data": [
{
"id": "328",
"type": "gobierto_common-vocabularies",
"attributes": {
"name_translations": {
"en": "New vocabulary",
"es": "Nuevo vocabulario"
},
"slug": "url-slug",
"terms": [
{
"id": 21547,
"name_translations": {
"en": "New term 1.1",
"es": "Nuevo termino 1.1"
},
"description_translations": {
"en": "New term 1.1 desc",
"es": "Nuevo termino 1.1 desc"
},
"slug": "term-slug-11",
"position": 0,
"level": 1,
"term_id": 21546,
"parent_external_id": "E0001",
"parent_id": "E0001",
"external_id": "E0001.1"
},
{
"id": 21546,
"name_translations": {
"en": "New term 1",
"es": "Nuevo termino 1"
},
"description_translations": {
"en": "New term 1 desc",
"es": "Nuevo termino 1 desc"
},
"slug": "term-slug",
"position": 0,
"level": 0,
"term_id": null,
"parent_external_id": null,
"parent_id": null,
"external_id": "E0001"
}
]
}
}//,
//{ ... },
//...
]
}
Get a single vocabulary
GET /api/v1/vocabularies/
Gets a single vocabulary. The request must include a valid token of an authorized admin.
The vocabulary identifier of the URL can be both:
- the vocabulary internal
id - the vocabulary
slugif exists
Headers:
Authorization:Bearer TOKENA valid token of an admin with permissions to create terms must be provided
Example of response:
{
"data": {
"id": "328",
"type": "gobierto_common-vocabularies",
"attributes": {
"name_translations": {
"en": "New vocabulary",
"es": "Nuevo vocabulario"
},
"slug": "url-slug",
"terms": [
{
"id": 21547,
"name_translations": {
"en": "New term 1.1",
"es": "Nuevo termino 1.1"
},
"description_translations": {
"en": "New term 1.1 desc",
"es": "Nuevo termino 1.1 desc"
},
"slug": "term-slug-11",
"position": 0,
"level": 1,
"term_id": 21546,
"parent_external_id": "E0001",
"parent_id": "E0001",
"external_id": "E0001.1"
},
{
"id": 21546,
"name_translations": {
"en": "New term 1",
"es": "Nuevo termino 1"
},
"description_translations": {
"en": "New term 1 desc",
"es": "Nuevo termino 1 desc"
},
"slug": "term-slug",
"position": 0,
"level": 0,
"term_id": null,
"parent_external_id": null,
"parent_id": null,
"external_id": "E0001"
}
]
}
}
}
Update a vocabulary
PUT /api/v1/vocabularies/
Updates an existing vocabulary. The request must include a valid token of an authorized admin.
The vocabulary identifier of the URL can be both:
- the vocabulary internal
id - the vocabulary
slugif exists
The body of the request should include only the attributes that needs to be updated. Any attribute in the body will be updated.
If the terms are included in the request, they will be updated also, following these rules:
- if the term has a
slugorexternal_idwill search for existing terms to update it - if it doesn't exist, the term will be created
For deleting existing terms in the vocabulary, refer to the term delete endpoint.
Headers:
Authorization:Bearer TOKENA valid token of an admin with permissions to create terms must be provided
Example of updating a vocabulary:
- updates the vocabulary english name
- creates a new term
New term 2 - updates the existing term
E0001.1with a new name
{
"data": {
"attributes": {
"name_translations": {
"en": "New vocabulary name"
},
"terms": [
{
"name_translations": {
"en": "New term 2",
"es": "Nuevo termino 2"
},
"slug": "term-slug-2",
"position": 1,
"level": 0,
"parent_id": null,
"external_id": "E00002"
},
{
"name_translations": {
"en": "New term 1.1 updated",
"es": "Nuevo termino 1.1 updated"
},
"external_id": "E0001.1"
}
]
}
}
}
Example of response:
{
"data": {
"id": "328",
"type": "gobierto_common-vocabularies",
"attributes": {
"name_translations": {
"en": "New vocabulary name",
"es": "Nuevo vocabulario"
},
"slug": "url-slug",
"terms": [
{
"id": 21547,
"name_translations": {
"en": "New term 1.1 updated",
"es": "Nuevo termino 1.1 updated"
},
"description_translations": {
"en": "New term 1.1 desc",
"es": "Nuevo termino 1.1 desc"
},
"slug": "term-slug-11",
"position": 0,
"level": 1,
"term_id": 21546,
"parent_external_id": "E0001",
"parent_id": "E0001",
"external_id": "E0001.1"
},
{
"id": 21546,
"name_translations": {
"en": "New term 1",
"es": "Nuevo termino 1"
},
"description_translations": {
"en": "New term 1 desc",
"es": "Nuevo termino 1 desc"
},
"slug": "term-slug",
"position": 0,
"level": 0,
"term_id": null,
"parent_external_id": null,
"parent_id": null,
"external_id": "E0001"
},
{
"id": 21548,
"name_translations": {
"en": "New term 2",
"es": "Nuevo termino 2"
},
"description_translations": null,
"slug": "term-slug-2",
"position": 1,
"level": 0,
"term_id": null,
"parent_external_id": null,
"parent_id": null,
"external_id": "E00002"
}
]
}
}
}
Updated about 1 year ago