Languages API

General notes

There always must be at least one language and at least one language must always be default. Default language can be changed by setting language of your choice to default and all other languages will be automatically switch to non-default state.

Default language cannot be deleted nor deactivated.

Content

Languages collection:

• [POST] create language
• [GET] index, searching and filtering languages

Single language:

• [GET] Language detail
• [PUT/PATCH] update language
• [DELETE] delete language

Languages collection

Create language

POST /api/languages

This method needs permission create on settings.

Method for creating new Language.

Request

Param	Type	Description	Requirements
id	string	ISO 639-2 Code	Required. Must be valid language identifier.
is_active	bool	Is active	Required.
is_default	bool	Is default	Required. Can be true only when is_active is true.

POST /api/languages HTTP/1.1
Content-Type: application/json

{
    "id": "eng",
    "is_active": true,
    "is_default": false
}

Responses

201 CREATED

New Language was successfully created.

POST /api/languages HTTP/1.1
Content-Type: application/json
Status-Code: 201

{
    "id": "eng",
    "name": "English",
    "original_name": "English",
    "is_active": true,
    "is_default": false,
    "created_at": "2019-08-07 12:29:14",
    "_links": [
        {
            "href": "/api/languages/eng",
            "rel": "self",
            "type": "GET"
        }
    ]
}

422 UNPROCESSABLE ENTITY

Validation error occurred.

POST /api/languages HTTP/1.1
Content-Type: application/json
Status-Code: 422

{
    "type": "ValidationError",
    "message": "The given data was invalid.",
    "id": "984a545c-7019-45b4-ab37-3c95da1ed13e",
    "errors": [
        {
            "field": "id",
            "message": "This language already exists."
        },
        {
            "field": "is_default",
            "message": "Inactive language cannot be default."
        }
    ]
}

---

Languages index

GET /api/languages

This method does not require any authentication. Without permission read on settings there are returned only active languages.

Get list of existing Languages.

Request

Index behaviour	Definition
Paginated by default	No
Sorting	id, original_name, created_at
Filters	id:enum, original_name:string, is_default:bool, is_active:bool
Embedded	-

GET /api/languages HTTP/1.1

Responses

200 OK

GET /api/languages HTTP/1.1
Content-Type: application/json
Status-Code: 200

{
    "items": [
        {
            "id": "eng",
            "name": "English",
            "original_name": "English",
            "is_active": true,
            "is_default": true,
            "created_at": "2019-08-07 11:11:51",
            "_links": [
                {
                    "href": "/api/languages/eng",
                    "rel": "self",
                    "type": "GET"
                }
            ]
        },
        {
            "id": "ces",
            "name": "Czech",
            "original_name": "čeština",
            "is_active": true,
            "is_default": false,
            "created_at": "2019-08-07 11:11:51",
            "_links": [
                {
                    "href": "/api/languages/ces",
                    "rel": "self",
                    "type": "GET"
                }
            ]
        }
    ]
}

---

---

Single Language

Language detail

GET /api/languages/{language_id}

This method does not require any authentication. Without permission read on settings there can be obtained only active language.

Get Language detail.

Request

GET /api/languages/eng HTTP/1.1

Responses

200 OK

GET /api/languages/eng HTTP/1.1
Content-Type: application/json
Status-Code: 200

{
    "id": "eng",
    "name": "English",
    "original_name": "English",
    "is_active": true,
    "is_default": true,
    "created_at": "2019-08-07 11:11:51",
    "_links": [
        {
            "href": "/api/languages/eng",
            "rel": "self",
            "type": "GET"
        }
    ]
}

404 NOT FOUND

Language was not found. Also returned when trying to get detail of inactive language without permission read on settings.

GET /api/languages/unk HTTP/1.1
Content-Type: application/json
Status-Code: 404

{
    "type": "NotFound",
    "message": "Required model was not found.",
    "id": "0cd85449-05fe-4866-9802-8192e6785fc7"
}

---

Update Language

PUT/PATCH /api/languages/{language_id}

This method needs permission update on settings.

Method for updating Language data.

Request

Param	Type	Description	Requirements
is_active	bool	Is active	Required. Can be false only when updated Language is not default.
is_default	bool	Is default	Required. Can be true only when updated Language is active. Cannot be set to false when Language is default.

For PATCH method any field can be omitted.

PUT /api/languages/eng HTTP/1.1
Content-Type: application/json

{
    "is_active": true,
    "is_default": true
}

Responses

200 OK

Language successfully updated.

PUT /api/languages/eng HTTP/1.1
Content-Type: application/json
Status-Code: 200

{
    "id": "eng",
    "name": "English",
    "original_name": "English",
    "is_active": true,
    "is_default": true,
    "created_at": "2019-08-07 11:11:51",
    "_links": [
        {
            "href": "/api/languages/eng",
            "rel": "self",
            "type": "GET"
        }
    ]
}

404 NOT FOUND

Language was not found.

PUT /api/languages/unk HTTP/1.1
Content-Type: application/json
Status-Code: 404

{
    "type": "NotFound",
    "message": "Required model was not found.",
    "id": "0cd85449-05fe-4866-9802-8192e6785fc7"
}

422 UNPROCESSABLE ENTITY

Validation error occurred.

PUT /api/languages/eng HTTP/1.1
Content-Type: application/json
Status-Code: 422

{
    "type": "ValidationError",
    "message": "The given data was invalid.",
    "id": "ad659bbb-608c-4cf9-8e5b-2b3078b25beb",
    "errors": [
        {
            "field": "is_default",
            "message": "Set another language as default."
        }
    ]
}

---

Delete Language

DELETE /api/languages/{language_id}

This method needs permission delete on settings.

Method for deleting Language.

Warning note: When language is deleted, all translations for this language will be deleted with it!

Request

DELETE /api/languages/eng HTTP/1.1

Responses

204 NO CONTENT

Language successfully deleted.

DELETE /api/languages/eng HTTP/1.1
Status-Code: 204

404 NOT FOUND

Language was not found.

DELETE /api/languages/unk HTTP/1.1
Content-Type: application/json
Status-Code: 404

{
    "type": "NotFound",
    "message": "Required model was not found.",
    "id": "0cd85449-05fe-4866-9802-8192e6785fc7"
}

423 LOCKED

Trying to delete default Language.

DELETE /api/languages/eng HTTP/1.1
Content-Type: application/json
Status-Code: 423

{
    "type": "Locked",
    "message": "Default language cannot be deleted.",
    "id": "7a0073d3-f344-4f59-88e1-64b0325baa85"
}