Taxons API¶
These endpoints will allow you to easily manage taxons. Base URI is /api/v1/taxons.
Taxon API response structure¶
If you request a taxon via API, you will receive an object with the following fields:
| Field | Description |
|---|---|
| id | Id of the taxon |
| code | Unique taxon identifier |
| root | The main ancestor of the taxon |
| parent | Parent of the taxon |
| translations | Collection of translations (each contains slug, name and description in the respective language) |
| position | The position of the taxon among other taxons |
| images | Images assigned to the taxon |
If you request for more detailed data, you will receive an object with the following fields:
| Field | Description |
|---|---|
| id | Id of the taxon |
| code | Unique taxon identifier |
| root | The main ancestor of the taxon |
| parent | Parent of the taxon |
| translations | Collection of translations (each contains slug, name and description in the respective language) |
| position | Position of the taxon among other taxons |
| images | Images assigned to the taxon |
| left | Location within the whole taxonomy |
| right | Location within the whole taxonomy |
| level | How deep the taxon is in the tree |
| children | Descendants of the taxon |
Note
Read more about Taxons.
Creating a Taxon¶
To create a new taxon you will need to call the /api/v1/taxons/ endpoint with the POST method.
Definition¶
POST /api/v1/taxons/
| Parameter | Parameter type | Description |
|---|---|---|
| Authorization | header | Token received during authentication |
| code | request | (unique) Taxon identifier |
| translations[‘localeCode’][‘name’] | request | Taxon name |
| translations[‘localeCode’][‘slug’] | request | (unique) Taxon slug |
Example¶
To create new taxon use the below method:
$ curl http://demo.sylius.com/api/v1/taxons/ \
-H "Authorization: Bearer SampleToken" \
-H "Content-Type: application/json" \
-X POST \
--data '
{
"code": "toys",
"translations": {
"en_US": {
"name": "Toys",
"slug": "category/toys"
}
}
}
'
Note
If you want to create your taxon as a child of another taxon, you should pass also the parent taxon’s code.
Exemplary Response¶
STATUS: 201 CREATED
{
"id": 11,
"code": "toys",
"children": [],
"left": 1,
"right": 2,
"level": 0,
"position": 1,
"translations": [],
"images": [],
"_links": {
"self": {
"href": "/api/v1/taxons/11"
}
}
}
Warning
If you try to create a taxon without code you will receive a 400 Bad Request error, that will contain validation errors.
Example¶
$ curl http://demo.sylius.com/api/v1/taxons/ \
-H "Authorization: Bearer SampleToken" \
-H "Content-Type: application/json" \
-X POST
Exemplary Response¶
STATUS: 400 Bad Request
{
"code": 400,
"message": "Validation Failed",
"errors": {
"children": {
"translations": {},
"images": {},
"code": {
"errors": [
"Please enter taxon code."
]
},
"parent": {}
}
}
}
You can also create a taxon with additional (not required) fields:
| Parameter | Parameter type | Description |
|---|---|---|
| translations[‘localeCode’][‘description’] | request | Description of the taxon |
| parent | request | The parent taxon’s code |
| images | request | Images codes assigned to the taxon |
Example¶
$ curl http://demo.sylius.com/api/v1/taxons/ \
-H "Authorization: Bearer SampleToken" \
-H "Content-Type: application/json" \
-X POST \
--data '
{
"code":"toys",
"translations":{
"en_US": {
"name": "Toys",
"slug": "category/toys",
"description": "Toys for boys"
}
},
"parent": "category",
"images": [
{
"type": "ford"
}
]
}
'
Exemplary Response¶
STATUS: 201 CREATED
{
"name": "toys",
"id": 9,
"code": "toys",
"root": {
"name": "Category",
"id": 1,
"code": "category",
"children": [
{
"name": "T-Shirts",
"id": 5,
"code": "t_shirts",
"children": [],
"left": 2,
"right": 7,
"level": 1,
"position": 0,
"translations": [],
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/5"
}
}
}
],
"left": 1,
"right": 10,
"level": 0,
"position": 0,
"translations": {
"en_US": {
"locale": "en_US",
"id": 1,
"name": "Category",
"slug": "category",
"description": "Consequatur illo amet aliquam."
}
},
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/1"
}
}
},
"parent": {
"name": "Category",
"id": 1,
"code": "category",
"children": [
{
"name": "T-Shirts",
"id": 5,
"code": "t_shirts",
"children": [],
"left": 2,
"right": 7,
"level": 1,
"position": 0,
"translations": [],
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/5"
}
}
}
],
"left": 1,
"right": 10,
"level": 0,
"position": 0,
"translations": {
"en_US": {
"locale": "en_US",
"id": 1,
"name": "Category",
"slug": "category",
"description": "Consequatur illo amet aliquam."
}
},
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/1"
}
}
},
"children": [],
"left": 8,
"right": 9,
"level": 1,
"position": 1,
"translations": {
"en_US": {
"locale": "en_US",
"id": 9,
"name": "toys",
"slug": "toys",
"description": "Toys for boys"
}
},
"images": [
{
"id": 1,
"type": "ford",
"path": "b9/65/01cec3d87aa2b819e195331843f6.jpeg"
}
],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/9"
}
}
}
Note
The images should be passed in array as an attribute (files) of request. See how it is done in Sylius here.
Getting a Single Taxon¶
To retrieve the details of a taxon you will need to call the /api/v1/taxons/{code} endpoint with the GET method.
Definition¶
GET /api/v1/taxons/{code}
| Parameter | Parameter type | Description |
|---|---|---|
| Authorization | header | Token received during authentication |
| code | url attribute | Identifier of the requested taxon |
Example¶
To see the details of the taxon with code = toys use the below method:
$ curl http://demo.sylius.com/api/v1/taxons/toys \
-H "Authorization: Bearer SampleToken" \
-H "Accept: application/json"
Note
The toys value was taken from the previous create response. Your value can be different. Check in the list of all taxons if you are not sure which id should be used.
Exemplary Response¶
STATUS: 200 OK
{
"name": "toys",
"id": 9,
"code": "toys",
"root": {
"name": "Category",
"id": 1,
"code": "category",
"children": [
{
"name": "T-Shirts",
"id": 5,
"code": "t_shirts",
"children": [],
"left": 2,
"right": 7,
"level": 1,
"position": 0,
"translations": [],
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/5"
}
}
}
],
"left": 1,
"right": 10,
"level": 0,
"position": 0,
"translations": {
"en_US": {
"locale": "en_US",
"id": 1,
"name": "Category",
"slug": "category",
"description": "Consequatur illo amet aliquam."
}
},
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/1"
}
}
},
"parent": {
"name": "Category",
"id": 1,
"code": "category",
"children": [
{
"name": "T-Shirts",
"id": 5,
"code": "t_shirts",
"children": [],
"left": 2,
"right": 7,
"level": 1,
"position": 0,
"translations": [],
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/5"
}
}
}
],
"left": 1,
"right": 10,
"level": 0,
"position": 0,
"translations": {
"en_US": {
"locale": "en_US",
"id": 1,
"name": "Category",
"slug": "category",
"description": "Consequatur illo amet aliquam."
}
},
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/1"
}
}
},
"children": [],
"left": 8,
"right": 9,
"level": 1,
"position": 1,
"translations": {
"en_US": {
"locale": "en_US",
"id": 9,
"name": "toys",
"slug": "toys",
"description": "Toys for boys"
}
},
"images": [
{
"id": 1,
"type": "ford",
"path": "b9/65/01cec3d87aa2b819e195331843f6.jpeg"
}
],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/9"
}
}
}
Collection of Taxons¶
To retrieve a paginated list of taxons you will need to call the /api/v1/taxons/ endpoint with the GET method.
Definition¶
GET /api/v1/taxons/
| 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 taxons use the below method:
Example¶
$ curl http://demo.sylius.com/api/v1/taxons/ \
-H "Authorization: Bearer SampleToken" \
-H "Accept: application/json"
Exemplary Response¶
STATUS: 200 OK
{
"page": 1,
"limit": 10,
"pages": 1,
"total": 5,
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/?page=1&limit=10"
},
"first": {
"href": "\/api\/v1\/taxons\/?page=1&limit=10"
},
"last": {
"href": "\/api\/v1\/taxons\/?page=1&limit=10"
}
},
"_embedded": {
"items": [
{
"name": "Category",
"id": 1,
"code": "category",
"position": 0,
"translations": {
"en_US": {
"locale": "en_US",
"id": 1,
"name": "Category",
"slug": "category",
"description": "Consequatur illo amet aliquam."
}
},
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/1"
}
}
},
{
"name": "T-Shirts",
"id": 5,
"code": "t_shirts",
"root": {
"name": "Category",
"id": 1,
"code": "category",
"position": 0,
"translations": [],
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/1"
}
}
},
"parent": {
"name": "Category",
"id": 1,
"code": "category",
"position": 0,
"translations": [],
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/1"
}
}
},
"position": 0,
"translations": {
"en_US": {
"locale": "en_US",
"id": 5,
"name": "T-Shirts",
"slug": "t-shirts",
"description": "Modi aut laborum aut sint aut ea itaque porro."
}
},
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/5"
}
}
},
{
"name": "Men",
"id": 6,
"code": "mens_t_shirts",
"root": {
"name": "Category",
"id": 1,
"code": "category",
"position": 0,
"translations": [],
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/1"
}
}
},
"parent": {
"name": "T-Shirts",
"id": 5,
"code": "t_shirts",
"position": 0,
"translations": [],
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/5"
}
}
},
"position": 0,
"translations": {
"en_US": {
"locale": "en_US",
"id": 6,
"name": "Men",
"slug": "t-shirts\/men",
"description": "Reprehenderit vero atque eaque sunt perferendis est."
}
},
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/6"
}
}
},
{
"name": "Women",
"id": 7,
"code": "womens_t_shirts",
"root": {
"name": "Category",
"id": 1,
"code": "category",
"position": 0,
"translations": [],
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/1"
}
}
},
"parent": {
"name": "T-Shirts",
"id": 5,
"code": "t_shirts",
"position": 0,
"translations": [],
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/5"
}
}
},
"position": 1,
"translations": {
"en_US": {
"locale": "en_US",
"id": 7,
"name": "Women",
"slug": "t-shirts\/women",
"description": "Illum quia beatae assumenda impedit."
}
},
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/7"
}
}
},
{
"name": "toys",
"id": 9,
"code": "toys",
"root": {
"name": "Category",
"id": 1,
"code": "category",
"position": 0,
"translations": [],
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/1"
}
}
},
"parent": {
"name": "Category",
"id": 1,
"code": "category",
"position": 0,
"translations": [],
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/1"
}
}
},
"position": 1,
"translations": {
"en_US": {
"locale": "en_US",
"id": 9,
"name": "toys",
"slug": "toys",
"description": "Toys for boys"
}
},
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/9"
}
}
}
]
}
}
Updating Taxon¶
To fully update a taxon you will need to call the /api/v1/taxons/{code} endpoint with the PUT method.
Definition¶
PUT /api/v1/taxons/{code}
| Parameter | Parameter type | Description |
|---|---|---|
| Authorization | header | Token received during authentication |
| code | url attribute | (unique) Identifier of the requested taxon |
| translations[‘localeCode’][‘name’] | request | (optional) Name of the taxon |
| translations[‘localeCode’][‘slug’] | request | (optional) (unique) Slug |
| translations[‘localeCode’][‘description’] | request | (optional) Description of the taxon |
| parent | request | (optional) The parent taxon’s code |
| images | request | (optional) Images codes assigned to the taxon |
Example¶
To fully update the taxon with code = toys use the below method:
$ curl http://demo.sylius.com/api/v1/taxons/toys \
-H "Authorization: Bearer SampleToken" \
-H "Content-Type: application/json" \
-X PUT \
--data '
{
"translations": {
"en_US": {
"name": "Dolls",
"slug": "dolls"
}
}
}
'
Exemplary Response¶
STATUS: 204 No Content
To update a taxon partially you will need to call the /api/v1/taxons/{code} endpoint with the PATCH method.
Definition¶
PATCH /api/v1/taxons/{code}
| Parameter | Parameter type | Description |
|---|---|---|
| Authorization | header | Token received during authentication |
| code | url attribute | (unique) Identifier of the requested taxon |
Example¶
To partially update the taxon with code = toys use the below method:
$ curl http://demo.sylius.com/api/v1/taxons/toys \
-H "Authorization: Bearer SampleToken" \
-H "Content-Type: application/json" \
-X PATCH \
--data '
{
"translations": {
"en_US": {
"name": "Dolls"
}
}
}
'
Exemplary Response¶
STATUS: 204 No Content
Deleting a Taxon¶
To delete a taxon you will need to call the /api/v1/taxons/{code} endpoint with the DELETE method.
Definition¶
DELETE /api/v1/taxons/{id}
| Parameter | Parameter type | Description |
|---|---|---|
| Authorization | header | Token received during authentication |
| code | url attribute | (unique) Identifier of the requested taxon |
Example¶
To delete the taxon with code = toys use the below method:
$ curl http://demo.sylius.com/api/v1/taxons/toys \
-H "Authorization: Bearer SampleToken" \
-H "Accept: application/json" \
-X DELETE
Exemplary Response¶
STATUS: 204 No Content
Set position of product in a Taxon¶
The products in Sylius can by grouped by taxon, therefore for every product there is a relation between the product and the assigned taxon.
What is more, every product can have a specific position in the taxon to which it belongs. To put products in a specific order
you will need to call the /api/v1/taxons/{code}/products endpoint wih the PUT method.
Definition¶
PUT /api/v1/taxons/{code}/products
| Parameter | Parameter type | Description |
|---|---|---|
| Authorization | header | Token received during authentication |
| code | url attribute | Code of the taxon in which the order of product will be changed |
Example¶
To change the order of products with codes yellow_t_shirt and princess_t_shirt in taxon with code womens_t_shirts use the below method:
$ curl http://demo.sylius.com/api/v1/taxons/womens_t_shirts/products \
-H "Authorization: Bearer SampleToken" \
-H "Content-Type: application/json" \
-X PUT \
--data '
{
"productsPositions": [
{
"productCode": "yellow_t_shirt",
"position": 3
},
{
"productCode": "princess_t_shirt",
"position": 0
}
]
}
'
Note
Remember the yellow_t_shirt and princess_t_shirt and womens_t_shirts are just exemplary codes and you can change them for the ones you need. Check in the list of all products if you are not sure which codes should be used.
Exemplary Response¶
STATUS: 204 NO CONTENT