Catalog of product categories - datawizio/pythonAPI GitHub Wiki

Catalog of product categories - is a hierarchic (tree) list of product categories. With the help of /categories/ resource one can get access to the list of product categories and can add new categories or delete not needed ones from the catalog.

The following commands are used with the /categories/ resource:

• GET - to receive one page of a collection
• POST - to add new category or list of categories to the Catalog of product categories
• OPTIONS - meta information about an object structure
• HEAD - similar to GET, but you receive only a heading of an answer

Command type: GET http://api.datawiz.io/api/v1/categories/

• .json - - to receive a response from a server in JSON format
• .api - to receive a response from a server in HTML format (test platform)

• format=json|api - similar to the stated above suffixes
• page_size={nn} - to establish a page size equal to {nn} objects
• page={n} - to load a page {n}
• parent_id={n} - to show only parent categories with category id={n}
• search = {substring} - - to show only the objects, which name contains "{substring}"
• ordering=name - to sort fields alphabetically (ascending)
• ordering=-name - to sort fields alphabetically

The "collection" object consists of four fields (count,next, previous,results).

An example of an empty collection returned by server:

GET http://api.datawiz.io/api/v1/categories/.json/?search=unknown-name

{
     "count": 0, 
     "next": null, 
     "previous": null, 
     "results": [] 
}

Example of a 2-element collection returned to a request: "to return all 'children' to indicated category": GET http://api.datawiz.io/api/v1/categories/?parent_id=2:

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"url": "http://api.datawiz.io/api/v1/categories/3/",
"category_id": "3",
"name": "cat1",
"parent_id": "2",
"parent_url": "http://api.datawiz.io/api/v1/categories/2/"
},
{
"url": "http://api.datawiz.io/api/v1/categories/4/",
"category_id": "4",
"name": "cat2",
"parent_id": "2",
"parent_url": "http://api.datawiz.io/api/v1/categories/2/"
}
]
}

In case of an error, server returns a response with a corresponding status and an error report in detail key:

HTTP 404 NOT FOUND 
Content-Type: application/json 
Vary: Accept 
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH 
{
"detail": "Not found"
}

Command type: POST http://api.datawiz.io/api/v1/categories/?format=json

• .json - to interact with a server in JSON format
• .api - to interact with a server in HTML format (test platform)

• format=json - to interact with a server in JSON format
• format=api - to interact with a server in HTML format (test platform)

A request contains a JSON-object of dictionary type, describing a new category. All the fields are important: category_id, parent_id and name. Field parent_id can have null value if the category doesn't have parent (superordinate category). The order of fields is not important.

Example of a request to add one new object to the Catalog of product categories: POST http://api.datawiz.io/api/v1/categories/.json

{
    "category_id": "124", 
    "name": "Bakery products", 
    "parent_id": "2", 
}

At a particular request processing the server returns 201 status code and object creation details.

Example of a server's response:

HTTP 201 CREATED
Content-Type: application/json
Vary: Accept
Location: http://api.datawiz.io/api/v1/categories/124/
Allow: GET, POST, HEAD, OPTIONS
{
"updated": 0,
"inserted": 1
}

• If an object with category_id already exists on the server, the request will replace the object on server without notification.
• • One can not add to server an object if there is no parent category with an indicated parent_id
• The name field can not be empty.

In case of an error, server returns a response with a corresponding status and an error report next to the field, related to that error. If an error is not only about one field, but the whole object, the report will appear next to the non_field_errors key.

Example of server's response with an error (name field is empty):

HTTP 400 BAD REQUEST 
Content-Type: application/json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS 
{
     "name": [
         "This field is required." 
     ] 
}

Command type: POST http://api.datawiz.io/api/v1/categories/?format=json

• .json - to interact with a server in JSON format
• .api - to interact with a server in HTML format (test platform)

• `format=json - to interact with a server in JSON format
• `format=api - to interact with a server in HTML format (test platform)

The request contains a JSON object of список (list) type, with one or more objects describing new category. Sending list type objects to server increases the speed of work.

Example of request for bulk adding of three new objects to the Catalog of product categories: POST http://api.datawiz.io/api/v1/categories/.json

[
    {
        "category_id": "124", 
        "name": "Bakery products", 
        "parent_id": "2" 
    },
    {
        "category_id": "125", 
        "name": "Dairy products", 
        "parent_id": "2" 
    },
    {
        "category_id": "126", 
        "name": "Gastronomy", 
        "parent_id": "2" 
    }
]

At a particular request processing the server returns 201 status code and statistics of added/altered objects.

Example of a server's response:

HTTP 201 CREATED
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"updated": 1,
"inserted": 2
}

In case of an error, server returns a response with a corresponding status and an error report in the object next to the field, related to that error. If an error is not only about one field, but the whole object, the report will appear next to the key non_field_errors.

Example of server's response with an error ( parent_id field of the first object has a mistake):

HTTP 400 BAD REQUEST
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
[
{
"parent_id": [
"Parent category with id=122 does not exist"
]
},
{}
]

Як видно, помилка відбулась в першому об'єкті, в полі parent_id. An error reason is also included.

The following JSON structure returns at this command:

OPTIONS /api/v1/categories/

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"name": "Category List",
"description": "Categories",
"renders": [
"application/json",
"text/html"
],
"parses": [
"application/json",
"application/x-www-form-urlencoded",
"multipart/form-data"
],
"actions": {
"POST": {
"url": {
"type": "field",
"required": false,
"read_only": true
},
"category_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 100
},
"name": {
"type": "string",
"required": true,
"read_only": false,
"label": "name",
"max_length": 200
},
"parent_id": {
"type": "string",
"required": false,
"read_only": false,
"max_length": 100
},
"parent_url": {
"type": "field",
"required": false,
"read_only": true
}
}
}
}

With the help of /categories/{id} resource you can get from server, fully or partially modify, or delete a particular object from the Catalog of product categories. To chose a particular object, one should change an {id} in the resource URL URL into an identifier of existing object form category_id field. The list of available objects and their identifiers can be received using 'GET /categories/' (for more details see chapter "[5. Resource /categories/ (Catalog of product categories, Collection)]")

The following commands are used with the /categories/{id} resource:

• GET - to get an object with category_id={id}
• PUT - to replace an object on server with a new object
• PATCH - to change the value of particular fields of an object
• DELETE - to delete from the Catalog of product categories an object with category_id={id}
• OPTIONS - meta information about an object structure
• HEAD - similar to GET, but you receive only a heading of an answer

Command type: GET http://api.datawiz.io/api/v1/categories/1-1 - to receive an object with category_id="1-1"

• .json - to receive a response from a server in JSON format
• .api - to receive a response from a server in HTML format (test platform)

• format=json|api - to set a data format. Similar to stated above suffixes

If one sends to server GET /categories/{id} command with an empty body, the server returns an object of a requested structure in JSON format or an error report.

For example, GET http://api.datawiz.io/api/v1/categories/126/.json:

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
{
"url": "http://api.datawiz.io/api/v1/categories/126/",
"category_id": "126",
"name": "Gastronomy",
"parent_id": "2",
"parent_url": "http://api.datawiz.io/api/v1/categories/2/"
}

In case of an error, server returns a response with a corresponding status and an error report in detail key:

HTTP 404 NOT FOUND 
Content-Type: application/json 
Vary: Accept 
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH 
{
"detail": "Not found"
}

This request works as two sequential requests: 1 to delete an object with old category_id = {id} (DELETE) 2 to create a new object with new category_id (POST)

Command type: PUT http://api.datawiz.io/api/v1/categories/126/.json - to replace the object with category_id="126" into another one

• .json - to interact with a server in JSON format
• .api - to interact with a server in HTML format (test platform)

• format=json - to interact with a server in JSON format
• format=api - to interact with a server in HTML format (test platform)

Request contains JSON object with new value of an object

All three fields are important: category_id, parent_id and name. parent_id field can have null value if the category doesn't have parent (superordinate category). The order of fields is not important.

Example of a request to replace an object in the list of point-of-sale terminals:

PUT http://api.datawiz.io/api/v1/categories/126/.json

{
     "category_id": "126", 
     "name": "Gastronomy(new)",
     "parent_id": "3"
}

Here fields parent_id and name are replaced. It should be stated that when changing the value of a key field (identifier, in this case- category_id), ) the field will change everywhere and all relations will be saved.

At a particular request processing the server returns 200 status code and object creation details.

Example of a server's response:

HTTP 201 CREATED 
Content-Type: application/json 
Vary: Accept 
Location: http://api.datawiz.io/api/v1/categories/126/
Allow: GET, POST, HEAD, OPTIONS 
{
"updated": 0,
"inserted": 1
}

• If an object with category_id already exists on the server, the request will replace the object on server without notification.
• • One can not add to server an object if there is already no parent category with an indicated parent_id
• The name field can not be empty.

In case of an error, server returns a response with a corresponding status and an error report next to the field, related to that error. If an error is not only about one field, but the whole object, the report will appear next to the non_field_errors key.

Example of server's response with an error (name field is empty):

HTTP 400 BAD REQUEST 
Content-Type: application/json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS 
{
     "name": [
         "This field is required." 
     ] 
}

CommandPATCH is used to change particular fields of an object. Command PATCH is similar to PUT, but here you can state not only an entire object, but only fields that have to be changed.

Command type: PATCH http://api.datawiz.io/api/v1/categories/1-100/.json - to remove particular fields of the object with category_id=1-100 to another ones

• .json - to interact with a server in JSON format
• .api - to interact with a server in HTML format (test platform)

• format=json - to interact with a server in JSON format
• format=api - to interact with a server in HTML format (test platform)

Request contains JSON object with new value of particular field of an object

All three fields are important: category_id, shop_id and name.

Example of a request to change the value of name field for an object with category_id=100 in the Catalog of product categories:

PATCH http://api.datawiz.io/api/v1/categories/100/.json

{
     "name": "category #100" 
}

At a particular request processing the server returns 200 status code and a changed object with filled url field.

Remark! If the category_idfield was changed, the url field will change as well!

Example of a server's response:

HTTP 200 OK 
Content-Type: application/json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS 
{
"url": "http://api.datawiz.io/api/v1/categories/100/",
"category_id": "100",
"name": "category #100",
"parent_id": "3",
"parent_url": "http://api.datawiz.io/api/v1/categories/3/"
}

• If an object with category_id already exists on the server, the request will replace the object on server without notification.
• • One can not add to server an object if there is already no parent category with an indicated parent_id
• The name field can not be empty.

In case of an error, server returns a response with a corresponding status and an error report next to the field, related to that error. If an error is not only about one field, but the whole object, the report will appear next to the key non_field_errors.

Example of server's response with an error (name field is empty):

HTTP 400 BAD REQUEST 
Content-Type: application/json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS 
{
     "name": [
         "This field is required." 
     ] 
}

Command DELETE is used to extract a particular object from the Catalog of product categories

Command type: DELETE http://api.datawiz.io/api/v1/categories/100/ - delete the object with category_id=100

• .json - to interact with a server in JSON format
• .api - to interact with a server in HTML format (test platform)

• format=json - to interact with a server in JSON format
• format=api - to interact with a server in HTML format (test platform)

The request doesn't have to contain anything.

At a particular request processing the server returns 204 NO CONTENT.

Example of a server's response:

HTTP 204 NO CONTENT 
Content-Type: application/json 
Vary: Accept 
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH

• • You can not delete a category if it has 'children' or some objects from the Catalog of products refer to it.

In case of an error, server returns a response with a corresponding status and an error report in detail:

HTTP 404 NOT FOUND 
Content-Type: application/json 
Vary: Accept 
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH 
{
"detail": "Not found"
}

The following JSON structure returns at this command:

OPTIONS /api/v1/categories/100/

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
{
"name": "Category Instance",
"description": "Categories",
"renders": [
"application/json",
"text/html"
],
"parses": [
"application/json",
"application/x-www-form-urlencoded",
"multipart/form-data"
],
"actions": {
"PUT": {
"url": {
"type": "field",
"required": false,
"read_only": true
},
"category_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 100
},
"name": {
"type": "string",
"required": true,
"read_only": false,
"label": "name",
"max_length": 200
},
"parent_id": {
"type": "string",
"required": false,
"read_only": false,
"max_length": 100
},
"parent_url": {
"type": "field",
"required": false,
"read_only": true
}
}
}
}