Currencies API

General notes

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

Default currency cannot be deleted nor deactivated.

Content

Currencies collection:

• [POST] create currency
• [GET] index, searching and filtering currencies

Single currency:

• [GET] Currency detail
• [PUT/PATCH] update currency
• [DELETE] delete currency

Currencies collection

Create currency

POST /api/currencies

This method needs permission create on settings.

Method for creating new Currency.

Request

Param	Type	Description	Requirements
id	string	ISO 4217 alpha	Required. Must be valid currency identifier.
is_active	bool	Is active	Required.
is_default	bool	Is default	Required. Can be true only when is_active is true.

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

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

Responses

201 CREATED

New Currency was successfully created.

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

{
    "id": "USD",
    "name": "United States dollar",
    "decimal_places": 2,
    "numeric_code": null,
    "symbol": "$",
    "is_active": true,
    "is_default": false,
    "created_at": "2019-08-07 14:33:46",
    "_links": [
        {
            "href": "/api/currencies/USD",
            "rel": "self",
            "type": "GET"
        }
    ]
}

422 UNPROCESSABLE ENTITY

Validation error occurred.

POST /api/currencies 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 currency already exists."
        },
        {
            "field": "is_default",
            "message": "Inactive currency cannot be default."
        }
    ]
}

---

Currencies index

GET /api/currencies

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

Get list of existing Currencies.

Request

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

GET /api/currencies HTTP/1.1

Responses

200 OK

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

{
    "items": [
        {
            "id": "CZK",
            "name": "Czech koruna",
            "decimal_places": 2,
            "numeric_code": null,
            "symbol": "Kč",
            "is_active": true,
            "is_default": true,
            "created_at": "2019-08-07 14:33:46",
            "_links": [
                {
                    "href": "/api/currencies/CZK",
                    "rel": "self",
                    "type": "GET"
                }
            ]
        },
        {
            "id": "USD",
            "name": "United States dollar",
            "decimal_places": 2,
            "numeric_code": null,
            "symbol": "$",
            "is_active": true,
            "is_default": false,
            "created_at": "2019-08-07 14:33:46",
            "_links": [
                {
                    "href": "/api/currencies/USD",
                    "rel": "self",
                    "type": "GET"
                }
            ]
        }
    ]
}

---

---

Single Currency

Currency detail

GET /api/currencies/{currency_id}

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

Get Currency detail.

Request

GET /api/currencies/USD HTTP/1.1

Responses

200 OK

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

{
    "id": "USD",
    "name": "United States dollar",
    "decimal_places": 2,
    "numeric_code": null,
    "symbol": "$",
    "is_active": true,
    "is_default": false,
    "created_at": "2019-08-07 14:33:46",
    "_links": [
        {
            "href": "/api/currencies/USD",
            "rel": "self",
            "type": "GET"
        }
    ]
}

404 NOT FOUND

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

GET /api/currencies/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 Currency

PUT/PATCH /api/currencies/{currency_id}

This method needs permission update on settings.

Method for updating Currency data.

Request

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

For PATCH method any field can be omitted.

PUT /api/currencies/USD HTTP/1.1
Content-Type: application/json

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

Responses

200 OK

Currency successfully updated.

PUT /api/currencies/USD HTTP/1.1
Content-Type: application/json
Status-Code: 200

{
    "id": "USD",
    "name": "United States dollar",
    "decimal_places": 2,
    "numeric_code": null,
    "symbol": "$",
    "is_active": true,
    "is_default": true,
    "created_at": "2019-08-07 14:33:46",
    "_links": [
        {
            "href": "/api/currencies/USD",
            "rel": "self",
            "type": "GET"
        }
    ]
}

404 NOT FOUND

Currency was not found.

PUT /api/currencies/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/currencies/USD 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 currency as default."
        }
    ]
}

---

Delete Currency

DELETE /api/currencies/{currency_id}

This method needs permission delete on settings.

Method for deleting Currency.

Warning note: When currency is deleted, all amounts for this currency might be deleted with it!

Request

DELETE /api/currencies/USD HTTP/1.1

Responses

204 NO CONTENT

Currency successfully deleted.

DELETE /api/currencies/USD HTTP/1.1
Status-Code: 204

404 NOT FOUND

Currency was not found.

DELETE /api/currencies/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 Currency.

DELETE /api/currencies/USD HTTP/1.1
Content-Type: application/json
Status-Code: 423

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