Skip to content

Latest commit

 

History

History
497 lines (408 loc) · 13.5 KB

zones.md

File metadata and controls

497 lines (408 loc) · 13.5 KB

Zones API

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

Zone structure

Zone API response structure

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

+-----------+------------------------+
| Field     | Description            |
+===========+========================+
| id        | Id of the zone         |
+-----------+------------------------+
| code      | Unique zone identifier |
+-----------+------------------------+
| name      | Name of the zone       |
+-----------+------------------------+
| type      | Type of the zone       |
+-----------+------------------------+

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

+-----------+------------------------+
| Field     | Description            |
+===========+========================+
| id        | Id of the zone         |
+-----------+------------------------+
| code      | Unique zone identifier |
+-----------+------------------------+
| name      | Name of the zone       |
+-----------+------------------------+
| type      | Type of the zone       |
+-----------+------------------------+
| scope     | Scope of the zone      |
+-----------+------------------------+
| members   | Members of the zone    |
+-----------+------------------------+
| createdAt | Date of creation       |
+-----------+------------------------+
| updatedAt | Date of last update    |
+-----------+------------------------+

Note

Read more about the Zone model in the component docs.

Creating a Zone

To create a new zone you will need to call the /api/v1/zones/{type} endpoint with the POST method.

Definition

POST /api/v1/zones/{type}

+---------------+----------------+--------------------------------------+
| Parameter     | Parameter type | Description                          |
+===============+================+======================================+
| Authorization | header         | Token received during authentication |
+---------------+----------------+--------------------------------------+
| type          | url attribute  | Type of a creating zone              |
+---------------+----------------+--------------------------------------+
| code          | request        | **(unique)** Zone identifier         |
+---------------+----------------+--------------------------------------+
| name          | request        | Name of the zone                     |
+---------------+----------------+--------------------------------------+
| scope         | request        | Scope of the zone                    |
+---------------+----------------+--------------------------------------+
| members       | request        | Members of the zone                  |
+---------------+----------------+--------------------------------------+

Note

Read more about Zone types in the component docs.

Example

To create a new country zone use the below method:

curl http://demo.sylius.com/api/v1/zones/country \
    -H "Authorization: Bearer SampleToken" \
    -H "Content-Type: application/json" \
    -X POST \
    --data '
        {
            "code": "EU",
            "name": "European Union",
            "scope": "all",
            "members": [
                {
                    "code": "PL"
                }
            ]
        }
    '

Exemplary Response

STATUS: 201 CREATED

{
    "id": 2,
    "code": "EU",
    "name": "European Union",
    "type": "country",
    "scope": "all",
    "_links": {
        "self": {
            "href": "\/api\/v1\/zones\/EU"
        }
    }
}

Warning

If you try to create a zone without name, code, scope or member, you will receive a 400 Bad Request error, that will contain validation errors.

Example

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

Exemplary Response

STATUS: 400 Bad Request

{
    "code": 400,
    "message": "Validation Failed",
    "errors": {
        "errors": [
            "Please add at least 1 zone member."
        ],
        "children": {
            "name": {
                "errors": [
                    "Please enter zone name."
                ]
            },
            "type": {},
            "scope": {
                "errors": [
                    "Please enter the scope."
                ]
            },
            "code": {
                "errors": [
                    "Please enter zone code."
                ]
            },
            "members": {}
        }
    }
}

Getting a Single Zone

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

Definition

GET /api/v1/zones/{code}

+---------------+----------------+--------------------------------------+
| Parameter     | Parameter type | Description                          |
+===============+================+======================================+
| Authorization | header         | Token received during authentication |
+---------------+----------------+--------------------------------------+
| code          | url attribute  | Unique zone identifier               |
+---------------+----------------+--------------------------------------+

Example

To see the details of the zone with code = EU use the below method:

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

Note

The EU code is an exemplary value. Your value can be different. Check in the list of all zones if you are not sure which code should be used.

Exemplary Response

STATUS: 200 OK

{
    "id": 2,
    "code": "EU",
    "name": "European Union",
    "type": "country",
    "scope": "all",
    "_links": {
        "self": {
            "href": "\/api\/v1\/zones\/EU"
        }
    }
}

Collection of Zones

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

Definition

GET /api/v1/zones/

+---------------------------------------+----------------+---------------------------------------------------+
| Parameter                             | Parameter type | Description                                       |
+=======================================+================+===================================================+
| Authorization                         | header         | Token received during authentication              |
+---------------------------------------+----------------+---------------------------------------------------+
| limit                                 | query          | *(optional)* Number of items to display per page, |
|                                       |                | by default = 10                                   |
+---------------------------------------+----------------+---------------------------------------------------+
| sorting['nameOfField']['direction']   | query          | *(optional)* Field and direction of sorting,      |
|                                       |                | by default 'desc' and 'createdAt'                 |
+---------------------------------------+----------------+---------------------------------------------------+

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

Example

curl http://demo.sylius.com/api/v1/zones/ \
    -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\/zones\/?page=1&limit=10"
        },
        "first": {
            "href": "\/api\/v1\/zones\/?page=1&limit=10"
        },
        "last": {
            "href": "\/api\/v1\/zones\/?page=1&limit=10"
        }
    },
    "_embedded": {
        "items": [
            {
                "id": 1,
                "code": "US",
                "name": "United States of America",
                "type": "country",
                "_links": {
                    "self": {
                        "href": "\/api\/v1\/zones\/US"
                    }
                }
            },
            {
                "id": 2,
                "code": "EU",
                "name": "European Union",
                "type": "country",
                "_links": {
                    "self": {
                        "href": "\/api\/v1\/zones\/EU"
                    }
                }
            }
        ]
    }
}

Updating a Zone

To fully update a zone you will need to call the /api/v1/zones/{code} endpoint with the PUT method.

Definition

    PUT /api/v1/zones/{code}

+---------------+----------------+--------------------------------------+
| Parameter     | Parameter type | Description                          |
+===============+================+======================================+
| Authorization | header         | Token received during authentication |
+---------------+----------------+--------------------------------------+
| code          | url attribute  | Unique zone identifier               |
+---------------+----------------+--------------------------------------+
| name          | request        | Name of the zone                     |
+---------------+----------------+--------------------------------------+
| scope         | request        | Scope of the zone                    |
+---------------+----------------+--------------------------------------+
| members       | request        | Members of the zone                  |
+---------------+----------------+--------------------------------------+

Example

To fully update the zone with code = EU use the below method:

curl http://demo.sylius.com/api/v1/zones/EU \
    -H "Authorization: Bearer SampleToken" \
    -H "Content-Type: application/json" \
    -X PUT \
    --data '
        {
            "name": "European Union Zone",
            "scope": "shipping",
            "members": [
                {
                    "code": "DE"
                }
            ]
        }
    '

Exemplary Response

STATUS: 204 No Content

If you try to perform a full zone update without all the required fields specified, you will receive a 400 Bad Request error.

Example

curl http://demo.sylius.com/api/v1/zones/EU \
    -H "Authorization: Bearer SampleToken" \
    -H "Content-Type: application/json" \
    -X PUT

Exemplary Response

STATUS: 400 Bad Request

{
    "code": 400,
    "message": "Validation Failed",
    "errors": {
        "errors": [
            "Please add at least 1 zone member."
        ],
        "children": {
            "name": {
                "errors": [
                    "Please enter zone name."
                ]
            },
            "type": {},
            "scope": {
                "errors": [
                    "Please enter the scope."
                ]
            },
            "code": {},
            "members": {}
        }
    }
}

To update a zone partially you will need to call the /api/v1/zones/{code} endpoint with the PATCH method.

Definition

PATCH /api/v1/zones/{code}

+---------------+----------------+--------------------------------------+
| Parameter     | Parameter type | Description                          |
+===============+================+======================================+
| Authorization | header         | Token received during authentication |
+---------------+----------------+--------------------------------------+
| code          | url attribute  | Unique zone identifier               |
+---------------+----------------+--------------------------------------+
| scope         | request        | Scope of the zone                    |
+---------------+----------------+--------------------------------------+

Example

To partially update the zone with code = EU use the below method:

curl http://demo.sylius.com/api/v1/zones/EU \
    -H "Authorization: Bearer SampleToken" \
    -H "Content-Type: application/json" \
    -X PATCH \
    --data '
        {
            "scope": "tax"
        }
    '

Exemplary Response

STATUS: 204 No Content

Deleting a Zone

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

Definition

DELETE /api/v1/zones/{code}

+---------------+----------------+--------------------------------------+
| Parameter     | Parameter type | Description                          |
+===============+================+======================================+
| Authorization | header         | Token received during authentication |
+---------------+----------------+--------------------------------------+
| code          | url attribute  | Unique zone identifier               |
+---------------+----------------+--------------------------------------+

Example

To delete the zone with code = EU use the below method:

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

Exemplary Response

STATUS: 204 No Content