Rest API Manual of products' categories - datawizio/pythonAPI GitHub Wiki

Manual of products' categories - is an hierarchical (treelike) list of products' categories. With the help of resource /categories/ you can get the access to the list of products' categories, and also add new categories to the manual and delete the unnecessary ones.

With resource /categories/ following commands are performed:

• GET - get one page of the collection
• POST - add new product's category or the list of categories to Manual of products' categories
• OPTIONS - meta-information on the object's structure
• HEAD - analog of GET, but returns only the title of the answer

Type of the command: GET http://api.datawiz.io/api/v1/categories/

• .json - Get the answer from the server in JSON format
• .api - Get the answer from the server in HTML format (test platform)

• format=json|api - analog of the above suffixes
• page_size={nn} - set up the size of the page equal {nn} objects
• page={n} - load the page {n}
• parent_id={n} - show only categories which belong to the parent category from category id={n}
• search = {substring} - show only objects in whose field name fragment"{substring}" was found
• ordering=name - sort in the field in alphabetical order (from smallest - to biggest)
• ordering=-name - sort in the field in alphabetical order

Object "collection" from four fields (count,next, previous,results).

Sample of empty collection received after request:

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

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

Sample of collection consisting of 2 elements received after request: "return all 'children' of the given 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 the case of the server error, the answer with the appropriate status returns, and also notification about the error posted in the key detail:

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

Type of the command: POST http://api.datawiz.io/api/v1/categories/?format=json

• .json - Interact with the server in JSON format
• .api - Interact with the server in HTML format (test platform)

• format=json - Interact with the server in JSON format
• format=api - Interact with the server in HTML format (test platform)

In the request JSON-object e.g. dictionary (dictionary) is delivered, which describes the new category. All fields are important: category_id, parent_id and name. Field parent_id can be null, if the category does not have the parent category (upper-level category). The order of the fields is not fundamental.

Sample of request to add one new object to Manual of products' categories: POST http://api.datawiz.io/api/v1/categories/.json

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

If the request was processed properly, server returns the code of status 201 and status of the object's creation.

Sample of the answer of the server:

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 the object with the identificator category_id already exists on the server, then the given request replaces the object on the server (replace) without warning.
• The object can not be added to the server if the parent category does not exist with the mentioned identificator parent_id
• Field name can not be empty .

In the case of the error server returns the answer with the corresponding status and the error notification noted opposite the name of the field with which this error is connected. If the error concerns not the certan field but the whole object, then the error notification will be noted opposite the key non_field_errors.

NOTE. Every error notification embodies collection (file) of lines of symbols.

Sample of the answer of the server if the error occurs (field name is empty):

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

Type of the command: POST http://api.datawiz.io/api/v1/categories/?format=json

• .json -Interact with the server in JSON format
• .api - Interact with the server in HTML format (test platform)

• `format=json - Interact with the server in JSON format
• `format=api - Interact with the server in HTML format (test platform)

In the request JSON-object e.g. list (list) is delivered, which contains one or more objects which describe the new category. Transfer to the server not one by one but block-by-block allows to increase the data transfer rate.

Sample of the request to add three new objects to Manual of products' categories: POST http://api.datawiz.io/api/v1/categories/.json

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

If the request was processed properly, server returns the code of status 201 and statistics of added/edited objects.

Sample of the answer of the server:

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

• If the object with the identificator category_id already exists on the server, then the given request replaces the object on the server (replace) without warning.
• The object can not be added to the server if the parent category does not ALREADY exist with the mentioned identificator parent_id
• Field name can not be empty.

In the case of the error server returns the answer with the corresponding status and the error notification noted in the position of the object where the error happenned, opposite the name of the field with which this error is connected. If the error concerns not the certan field but the whole object, then the error notification will be noted opposite the key non_field_errors.

NOTE. Every error notification embodies collection (file) of lines of symbols.

Sample of the answer of the server if the error occurs (field parent_id of the first object is transfered incorrectly):

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"
]
},
{}
]

Apparently the error occured in the first object in the field parent_id. Here the reason of the error is noted.

JSON-structure is returned when the given command is performed:

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
}
}
}
}

When using resource /categories/{id} you can get from the server, modificate entirely or partly, and also delete the chosen object from Manual of products' categories. In order to choose the needed object you should change {id} in URL resource to the identificator from field category_id of the existing object. The list of the existing objects and their identificators you can get when using command 'GET /categories/' (for more information see paragraph "[5. Resource /categories/ (Manual of products' categories, Collection)]")

With resource /categories/{id} following commands are performed:

• GET - get object from category_id={id}
• PUT - entirely replace the objet on the server by a new one
• PATCH - change the meaning of specific firlds of the object
• DELETE - remove from Manual of products' categories object with category_id={id}
• OPTIONS - meta-information on the object's structure
• HEAD - analog of GET, but returns only the title of the answer

Type of the command: GET http://api.datawiz.io/api/v1/categories/1-1 - get object from category_id="1-1"

• .json - Get the answer from the server in JSON format
• .api - Get the answer from the server in HTML format (test platform)

• format=json|api - determine data format. Analog of the above suffixes

When the command GET /categories/{id} is send to the server with the empty body request, server returns object of the stated structure in JSON format or the error notification.

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": "Cookery",
"parent_id": "2",
"parent_url": "http://api.datawiz.io/api/v1/categories/2/"
}

In the case of the error, server returns the answer with the appropriate status, and also the error notification posted in the key detail:

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

Practically this request works as two sequential requests: 1 Delete the object with the old category_id = {id} (DELETE) 2 Create new object with new category_id (POST)

Type of the command: PUT http://api.datawiz.io/api/v1/categories/126/.json - replace the object from category_id="126" with another

• .json - Interact with the server in JSON format
• .api - Interact with the server in HTML format (test platform)

• format=json - Interact with the server in JSON format
• format=api - Interact with the server in HTML format (test platform)

In the request JSON-object is transmitted with the new meaning of the object

All three fields are important: category_id, parent_id and name. Field parent_id can be null, if the category has no parent (upper-level category). The order of the fields is not fundamental.

Sample of request to replace object in List of cashiers' terminals:

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

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

Here fields parent_id and name are replaced. Notice that if the meaning of the key field is replaced (identifier, in our case - category_id), this field changes everywhere and all the connections will be saved.

If the request was processed properly, server returns the code of status 200 and status of the object's creation.

Sample of the answer of the server:

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 the object with the identificator category_id already exists on the server, then the given request replaces the object on the server (replace) without warning.
• The object can not be added to the server if the parent category does not ALREADY exist with the mentioned identificator parent_id
• Field name can not be empty.

In the case of the error server returns the answer with the corresponding status and the error notification noted opposite the name of the field with which this error is connected. If the error concerns not the certan field but the whole object, then the error notification will be noted opposite the key non_field_errors.

NOTE. Every error notification embodies collection (file) of lines of symbols.

Sample of the answer of the server if the error occurs (field name is empty):

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

Command PATCH is used is specific fields of the object should be changed. Command PATCH is similar to command PUT, but here you can instruct not the entire object, but only those fields needed to be changed.

Type of command: PATCH http://api.datawiz.io/api/v1/categories/1-100/.json - change specific fields of the object from category_id=1-100 to others

• .json - Interact with the server in JSON format
• .api - Interact with the server in HTML format (test platform)

• format=json - Interact with the server in JSON format
• format=api - Interact with the server in HTML format (test platform)

In the request JSON-object with the new meaning of specific fields of objects is delivered

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

Sample of request to change the meaning of the field name for the object from category_id=100 in Manual of products' categories:

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

{
     "name": "category #100" 
}

If the request was processed properly, server returns the code of status 200 and the modified object with completed field url.

NOTE! If the field category_id was changed, then the field url also changes!

Sample of the answer of the server:

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 the object with the identificator category_id already exists on the server, then the given request replaces the object on the server (replace) without warning.
• The object can not be added to the server if the parent category does not ALREADY exist with the mentioned identificator parent_id
• Field name can not be empty.

In the case of the error server returns the answer with the corresponding status and the error notification noted opposite the name of the field with which this error is connected. If the error concerns not the certan field but the whole object, then the error notification will be noted opposite the key non_field_errors.

NOTE. Every error notification embodies collection (file) of lines of symbols.

Sample of the answer of the server if the error occurs (field name 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 delete the certain object from Manual of products' categories

Type of command: DELETE http://api.datawiz.io/api/v1/categories/100/ - delete object from category_id=100

• .json - Interact with the server in JSON format
• .api - Interact with the server in HTML format (test platform)

• format=json - Interact with the server in JSON format
• format=api - Interact with the server in HTML format (test platform)

Nothing should be transmitted in the request.

If the request was processed properly, server returns the code of status 204 NO CONTENT.

Sample of the answer of the server:

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

• The category can not be deleted if it has 'children' and/or objects from Manual of nomenclature (Manual of products') are referred to it

In the case of the error server returns the answer with the corresponding status and the error notification noted in the key detail:

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

When the command is performed the given JSON-structure is returned:

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
}
}
}
}