kenaug74/Sylius
1
0
Fork 0
mirror of https://github.com/Sylius/Sylius.git synced 2026-07-14 17:10:53 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 5
Sylius/docs/api/product_attributes.rst
Łukasz Chruściel dd39ffa6a0
[Docs] Improved coping UX
2020-03-06 09:46:59 +01:00

682 lines
24 KiB
ReStructuredText
Raw Blame History

Product Attributes API
======================
These endpoints will allow you to easily manage product attributes. Base URI is `/api/v1/product-attributes`.
Product Attribute API response structure
----------------------------------------
If you request a product attribute via API, you will receive an object with the following fields:
+--------------+----------------------------------------------------------------------+
| Field | Description |
+==============+======================================================================+
| id | Id of the product attribute |
+--------------+----------------------------------------------------------------------+
| code | Unique product attribute identifier |
+--------------+----------------------------------------------------------------------+
| position | The position of the product attribute among other product attributes |
+--------------+----------------------------------------------------------------------+
| type | Type of the product attribute (for example text) |
+--------------+----------------------------------------------------------------------+
| translations | Collection of translations (each contains name in given language) |
+--------------+----------------------------------------------------------------------+
If you request for more detailed data, you will receive an object with the following fields:
+--------------+----------------------------------------------------------------------+
| Field | Description |
+==============+======================================================================+
| id | Id of the product attribute |
+--------------+----------------------------------------------------------------------+
| code | Unique product attribute identifier |
+--------------+----------------------------------------------------------------------+
| position | The position of the product attribute among other product attributes |
+--------------+----------------------------------------------------------------------+
| type | Type of the product attribute (for example text) |
+--------------+----------------------------------------------------------------------+
| translations | Collection of translations (each contains name in given language) |
+--------------+----------------------------------------------------------------------+
| updatedAt | Last update date of the product attribute |
+--------------+----------------------------------------------------------------------+
| createdAt | Creation date of the product attribute |
+--------------+----------------------------------------------------------------------+
.. note::
Read more about :doc:`Product Attributes in the component docs</components_and_bundles/components/Product/models>`.
Creating a Product Attribute
----------------------------
To create a new product attribute you will need to call the ``/api/v1/products-attributes/{type}`` endpoint with the ``POST`` method.
Definition
^^^^^^^^^^
.. code-block:: text
POST /api/v1/product-attributes/{type}
+---------------+----------------+--------------------------------------------------+
| Parameter | Parameter type | Description |
+===============+================+==================================================+
| Authorization | header | Token received during authentication |
+---------------+----------------+--------------------------------------------------+
| type | url attribute | Type of the product attribute (for example text) |
+---------------+----------------+--------------------------------------------------+
| code | request | **(unique)** Product attribute identifier |
+---------------+----------------+--------------------------------------------------+
Example
^^^^^^^
To create a new text product attribute use the below method:
.. code-block:: bash
curl http://demo.sylius.com/api/v1/product-attributes/text \
-H "Authorization: Bearer SampleToken" \
-H "Content-Type: application/json" \
-X POST \
--data '
{
"code": "mug_material"
}
'
Exemplary Response
^^^^^^^^^^^^^^^^^^
.. code-block:: text
STATUS: 201 CREATED
.. code-block:: json
{
"id": 1,
"code": "mug_material",
"type": "text",
"configuration": [],
"position": 0,
"translations": {},
"_links": {
"self": {
"href": "\/api\/v1\/product-attributes\/mug_material"
}
}
}
.. warning::
If you try to create a product attribute without code you will receive a ``400 Bad Request`` error, that will contain validation errors.
.. code-block:: bash
curl http://demo.sylius.com/api/v1/product-attributes/text \
-H "Authorization: Bearer SampleToken" \
-H "Content-Type: application/json" \
-X POST \
Exemplary Response
^^^^^^^^^^^^^^^^^^
.. code-block:: text
STATUS: 400 BAD REQUEST
.. code-block:: json
{
"code": 400,
"message": "Validation Failed",
"errors": {
"children": {
"type": {},
"position": {},
"translations": {},
"code": {
"errors": [
"Please enter attribute code."
]
},
"configuration": {
"children": {
"min": {},
"max": {}
}
}
}
}
}
You can also create a product attribute with additional (not required) fields:
+------------------------------------+----------------+----------------------------------------------------------------------------+
| Parameter | Parameter type | Description |
+====================================+================+============================================================================+
| position | request | Position within sorted product attribute list of the new product attribute |
+------------------------------------+----------------+----------------------------------------------------------------------------+
| translations['localeCode']['name'] | request | Name of the product attribute |
+------------------------------------+----------------+----------------------------------------------------------------------------+
Some of product attributes have also their own (optional) configuration:
+------------------------+----------------------------+---------------------------------------------------------------------------------+
| Product attribute type | configuration construction | Description |
+========================+============================+=================================================================================+
| text | configuration['min'] | Both field must be defined together. |
| | configuration['max'] | They described minimal and maximal length of the text attribute. |
+------------------------+----------------------------+---------------------------------------------------------------------------------+
| select | configuration['multiple'] | The *multiple*, *min*, and *max* must be defined together. They allow to select |
| | configuration['min'] | several values, limited by minimal and maximal amount of entries. |
| | configuration['max'] | The *choices* is an array of available options in the product attribute. |
| | configuration['choices'] | |
+------------------------+----------------------------+---------------------------------------------------------------------------------+
.. note::
You can also see exemplary request about creating configured select product attribute
`here <https://github.com/Sylius/Sylius/blob/master/tests/Controller/ProductAttributeApiTest.php>`_.
Example
^^^^^^^
.. code-block:: bash
curl http://demo.sylius.com/api/v1/product-attributes/text/ \
-H "Authorization: Bearer SampleToken" \
-H "Content-Type: application/json" \
-X POST \
--data '
{
"code": "mug_material",
"translations": {
"de_CH": {
"name": "Becher Material"
},
"en_US": {
"name": "Mug material"
}
}
}
'
Exemplary Response
^^^^^^^^^^^^^^^^^^
.. code-block:: text
STATUS: 201 CREATED
.. code-block:: json
{
"id": 1,
"code": "mug_material",
"type": "text",
"configuration": [],
"position": 0,
"createdAt": "2017-02-24T16:14:05+0100",
"updatedAt": "2017-02-24T16:14:05+0100",
"translations": {
"de_CH": {
"id": 1,
"locale": "de_CH",
"name": "Becher Material"
},
"en_US": {
"id": 2,
"locale": "en_US",
"name": "Mug material"
}
},
"_links": {
"self": {
"href": "\/api\/v1\/product-attributes\/mug_material"
}
}
}
Getting a Single Product Attribute
----------------------------------
To retrieve the details of a product attribute you will need to call the ``/api/v1/product-attributes/code`` endpoint with the ``GET`` method.
Definition
^^^^^^^^^^
.. code-block:: text
GET /api/v1/product-attributes/{code}
+---------------+----------------+------------------------------------------+
| Parameter | Parameter type | Description |
+===============+================+==========================================+
| Authorization | header | Token received during authentication |
+---------------+----------------+------------------------------------------+
| code | url attribute | Code of the requested product attribute |
+---------------+----------------+------------------------------------------+
Example
^^^^^^^
To see the details of the product attribute with ``code = sticker_paper`` use the below method:
.. code-block:: bash
curl http://demo.sylius.com/api/v1/product-attributes/sticker_paper \
-H "Authorization: Bearer SampleToken" \
-H "Accept: application/json"
.. note::
The *sticker_paper* code is just an example. Your value can be different.
Exemplary Response
^^^^^^^^^^^^^^^^^^
.. code-block:: text
STATUS: 200 OK
.. code-block:: json
{
"id": 2,
"code": "sticker_paper",
"type": "text",
"configuration": [],
"position": 1,
"createdAt": "2017-03-29T10:05:00+0200",
"updatedAt": "2017-03-31T09:48:37+0200",
"translations": {
"en_US": {
"locale": "en_US",
"id": 2,
"name": "Sticker paper"
}
},
"_links": {
"self": {
"href": "\/api\/v1\/product-attributes\/sticker_paper"
}
}
}
Collection of Product Attributes
--------------------------------
To retrieve a paginated list of product attributes you will need to call the ``/api/v1/product-attributes/`` endpoint with the ``GET`` method.
Definition
^^^^^^^^^^
.. code-block:: text
GET /api/v1/product-attributes/
+---------------+----------------+-------------------------------------------------------------------+
| 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 product attributes use the below method:
Example
^^^^^^^
.. code-block:: bash
curl http://demo.sylius.com/api/v1/product-attributes/ \
-H "Authorization: Bearer SampleToken" \
-H "Accept: application/json"
Exemplary Response
^^^^^^^^^^^^^^^^^^
.. code-block:: text
STATUS: 200 OK
.. code-block:: json
{
"page": 1,
"limit": 10,
"pages": 1,
"total": 10,
"_links": {
"self": {
"href": "\/api\/v1\/product-attributes\/?page=1&limit=10"
},
"first": {
"href": "\/api\/v1\/product-attributes\/?page=1&limit=10"
},
"last": {
"href": "\/api\/v1\/product-attributes\/?page=1&limit=10"
}
},
"_embedded": {
"items": [
{
"id": 1,
"code": "mug_material",
"type": "select",
"position": 0,
"translations": {
"en_US": {
"locale": "en_US",
"id": 1,
"name": "Mug material"
}
},
"_links": {
"self": {
"href": "\/api\/v1\/product-attributes\/mug_material"
}
}
},
{
"id": 2,
"code": "sticker_paper",
"type": "text",
"position": 1,
"translations": {
"en_US": {
"locale": "en_US",
"id": 2,
"name": "Sticker paper"
}
},
"_links": {
"self": {
"href": "\/api\/v1\/product-attributes\/sticker_paper"
}
}
},
{
"id": 3,
"code": "sticker_resolution",
"type": "text",
"position": 2,
"translations": {
"en_US": {
"locale": "en_US",
"id": 3,
"name": "Sticker resolution"
}
},
"_links": {
"self": {
"href": "\/api\/v1\/product-attributes\/sticker_resolution"
}
}
},
{
"id": 4,
"code": "book_author",
"type": "text",
"position": 3,
"translations": {
"en_US": {
"locale": "en_US",
"id": 4,
"name": "Book author"
}
},
"_links": {
"self": {
"href": "\/api\/v1\/product-attributes\/book_author"
}
}
},
{
"id": 5,
"code": "book_isbn",
"type": "text",
"position": 4,
"translations": {
"en_US": {
"locale": "en_US",
"id": 5,
"name": "Book ISBN"
}
},
"_links": {
"self": {
"href": "\/api\/v1\/product-attributes\/book_isbn"
}
}
},
{
"id": 6,
"code": "book_pages",
"type": "integer",
"position": 5,
"translations": {
"en_US": {
"locale": "en_US",
"id": 6,
"name": "Book pages"
}
},
"_links": {
"self": {
"href": "\/api\/v1\/product-attributes\/book_pages"
}
}
},
{
"id": 7,
"code": "book_genre",
"type": "select",
"position": 6,
"translations": {
"en_US": {
"locale": "en_US",
"id": 7,
"name": "Book genre"
}
},
"_links": {
"self": {
"href": "\/api\/v1\/product-attributes\/book_genre"
}
}
},
{
"id": 8,
"code": "t_shirt_brand",
"type": "text",
"position": 7,
"translations": {
"en_US": {
"locale": "en_US",
"id": 8,
"name": "T-Shirt brand"
}
},
"_links": {
"self": {
"href": "\/api\/v1\/product-attributes\/t_shirt_brand"
}
}
},
{
"id": 9,
"code": "t_shirt_collection",
"type": "text",
"position": 8,
"translations": {
"en_US": {
"locale": "en_US",
"id": 9,
"name": "T-Shirt collection"
}
},
"_links": {
"self": {
"href": "\/api\/v1\/product-attributes\/t_shirt_collection"
}
}
},
{
"id": 10,
"code": "t_shirt_material",
"type": "text",
"position": 9,
"translations": {
"en_US": {
"locale": "en_US",
"id": 10,
"name": "T-Shirt material"
}
},
"_links": {
"self": {
"href": "\/api\/v1\/product-attributes\/t_shirt_material"
}
}
}
]
}
}
Updating a Product Attribute
----------------------------
To fully update a product attribute you will need to call the ``/api/v1/product-attributes/code`` endpoint with the ``PUT`` method.
Definition
^^^^^^^^^^
.. code-block:: text
PUT /api/v1/product-attributes/{code}
+-----------------------------------+----------------+--------------------------------------+
| Parameter | Parameter type | Description |
+===================================+================+======================================+
| Authorization | header | Token received during authentication |
+-----------------------------------+----------------+--------------------------------------+
| code | url attribute | Unique product attribute identifier |
+-----------------------------------+----------------+--------------------------------------+
Example
^^^^^^^
To fully update the product attribute with ``code = mug_material`` use the below method:
.. code-block:: bash
curl http://demo.sylius.com/api/v1/product-attributes/mug_material \
-H "Authorization: Bearer SampleToken" \
-H "Content-Type: application/json" \
-X PUT \
--data '
{
"translations": {
"en_US": {
"name": "Mug material"
}
}
}
'
Exemplary Response
^^^^^^^^^^^^^^^^^^
.. code-block:: text
STATUS: 204 No Content
To update a product attribute partially you will need to call the ``/api/v1/product-attributes/code`` endpoint with the ``PATCH`` method.
Definition
^^^^^^^^^^
.. code-block:: text
PATCH /api/v1/product-attributes/{code}
+---------------+----------------+--------------------------------------+
| Parameter | Parameter type | Description |
+===============+================+======================================+
| Authorization | header | Token received during authentication |
+---------------+----------------+--------------------------------------+
| code | url attribute | Unique product attribute identifier |
+---------------+----------------+--------------------------------------+
Example
^^^^^^^
To partially update the product attribute with ``code = mug_material`` use the below method:
.. code-block:: bash
curl http://demo.sylius.com/api/v1/product-attributes/mug_material \
-H "Authorization: Bearer SampleToken" \
-H "Content-Type: application/json" \
-X PATCH \
--data '
{
"translations": {
"en_US": {
"name": "Mug material"
}
}
}
'
Exemplary Response
^^^^^^^^^^^^^^^^^^
.. code-block:: text
STATUS: 204 No Content
Deleting a Product Attribute
----------------------------
To delete a product attribute you will need to call the ``/api/v1/product-attributes/code`` endpoint with the ``DELETE`` method.
Definition
^^^^^^^^^^
.. code-block:: text
DELETE /api/v1/product-attributes/{code}
+---------------+----------------+--------------------------------------+
| Parameter | Parameter type | Description |
+===============+================+======================================+
| Authorization | header | Token received during authentication |
+---------------+----------------+--------------------------------------+
| code | url attribute | Unique product attribute identifier |
+---------------+----------------+--------------------------------------+
Example
^^^^^^^
To delete the product attribute with ``code = mug_material`` use the below method:
.. code-block:: bash
curl http://demo.sylius.com/api/v1/product-attributes/mug_material \
-H "Authorization: Bearer SampleToken" \
-H "Accept: application/json" \
-X DELETE
Exemplary Response
^^^^^^^^^^^^^^^^^^
.. code-block:: text
STATUS: 204 No Content
Reference in a new issue View git blame Copy permalink