Countries API

These endpoints will allow you to easily manage countries. Base URI is /api/v1/countries.

Country API response structure

If you request a country via API, you will receive an object with the following fields:

Field	Description
id	Id of the country
code	Unique country identifier

If you request for more detailed data, you will receive an object with the following fields:

Field	Description
id	Id of the country
code	Unique country identifier
enabled	Information says if the country is enabled (default: false)
provinces	Collection of the country’s provinces

Note

Read more about Countries in the component docs.

Creating a Country

To create a new country you will need to call the /api/v1/countries/ endpoint with the POST method.

Definition

POST /api/v1/countries/

Parameter	Parameter type	Description
Authorization	header	Token received during authentication
code	request	(unique) Country identifier

Example

$ curl http://demo.sylius.com/api/v1/countries/ \
    -H "Authorization: Bearer SampleToken" \
    -H "Content-Type: application/json" \
    -X POST \
    --data '
        {
            "code": "PL"
        }
    '

Exemplary Response

STATUS: 201 CREATED

{
    "id": 2,
    "code": "PL",
    "provinces": [],
    "enabled": false,
    "_links": {
        "self": {
            "href": "\/api\/v1\/countries\/PL"
        }
    }
}

If you try to create a country without code you will receive a 400 Bad Request error.

Example

$ curl http://demo.sylius.com/api/v1/countries/ \
    -H "Authorization: Bearer SampleToken" \
    -H "Content-Type: application/json" \
    -X POST

Exemplary Response

STATUS: 400 Bad Request

{
    "code": 400,
    "message": "Validation Failed",
    "errors": {
        "children": {
            "provinces": {},
            "enabled": {},
            "code": {
                "errors": [
                  "Please enter country ISO code."
                ]
            }
        }
    }
}

You can also create a country with additional (not required) fields:

Parameter	Parameter type	Description
enabled	request	Information says if the country is enabled (default: false)
provinces	request	Collection of the country’s provinces

Example

$ curl http://demo.sylius.com/api/v1/countries/ \
    -H "Authorization: Bearer SampleToken" \
    -H "Content-Type: application/json" \
    -X POST \
    --data '
        {
            "code":"PL",
            "enabled": true,
            "provinces": [
                {
                    "name": "mazowieckie",
                    "code": "PL-MZ"
                }
            ]
        }
    '

Exemplary Response

STATUS: 201 CREATED

{
    "id": 4,
    "code": "PL",
    "provinces": [
        {
            "id": 1,
            "code": "PL-MZ",
            "name": "mazowieckie",
            "_links": {
                "self": {
                    "href": "\/api\/v1\/countries\/PL\/provinces\/PL-MZ"
                },
                "country": {
                    "href": "\/api\/v1\/countries\/PL"
                }
            }
        }
    ],
    "enabled": true,
    "_links": {
        "self": {
            "href": "\/api\/v1\/countries\/PL"
        }
    }
}

Getting a Single Country

To retrieve the details of a country you will need to call the /api/v1/countries/{code} endpoint with the GET method.

Definition

GET /api/v1/countries/{code}

Parameter	Parameter type	Description
Authorization	header	Token received during authentication
code	url attribute	Code of the requested country

Example

To see the details of the country with code = US use the below method:

$ curl http://demo.sylius.com/api/v1/countries/US \
   -H "Authorization: Bearer SampleToken" \
   -H "Accept: application/json"

Note

The US code is just an example. Your value can be different.

Exemplary Response

STATUS: 200 OK

{
    "id": 1,
    "code": "US",
    "provinces": [],
    "enabled": true,
    "_links": {
        "self": {
            "href": "\/api\/v1\/countries\/US"
        }
    }
}

Collection of Countries

To retrieve a paginated list of countries you will need to call the /api/v1/countries/ endpoint with the GET method.

Definition

GET /api/v1/countries/

Parameter	Parameter type	Description
Authorization	header	Token received during authentication
page	query	(optional) Number of the page, by default = 1
paginate	query	(optional) Number of items to display per page, by default = 10

To see the first page of all countries use the below method:

Example

$ curl http://demo.sylius.com/api/v1/countries/ \
    -H "Authorization: Bearer SampleToken" \
    -H "Accept: application/json"

Exemplary Response

STATUS: 200 OK

{
    "page": 1,
    "limit": 10,
    "pages": 1,
    "total": 2,
    "_links": {
        "self": {
            "href": "\/api\/v1\/countries\/?page=1&limit=10"
        },
        "first": {
            "href": "\/api\/v1\/countries\/?page=1&limit=10"
        },
        "last": {
            "href": "\/api\/v1\/countries\/?page=1&limit=10"
        }
    },
    "_embedded": {
        "items": [
            {
                "id": 1,
                "code": "US",
                "_links": {
                    "self": {
                        "href": "\/api\/v1\/countries\/US"
                    }
                }
            },
            {
                "id": 4,
                "code": "PL",
                "_links": {
                    "self": {
                        "href": "\/api\/v1\/countries\/PL"
                    }
                }
            }
        ]
    }
}

Deleting a Country

To delete a country you will need to call the /api/v1/countries/{code} endpoint with the DELETE method.

Definition

DELETE /api/v1/countries/{code}

Parameter	Parameter type	Description
Authorization	header	Token received during authentication
code	url attribute	Code of the removed country

Example

$ curl http://demo.sylius.com/api/v1/countries/PL \
    -H "Authorization: Bearer SampleToken" \
    -H "Accept: application/json" \
    -X DELETE

Exemplary Response

STATUS: 204 No Content