Rest API Catalog of products - datawizio/pythonAPI GitHub Wiki

9. Resource /products/ (Catalog of products, Collection)

Catalog of products - is a list of product names and corresponding identifiers. With the help of /products/ resource one can get access to the list of products and add new data to a catalog.

9.1. Object structure:

Field name Field type Size Required Read only Remark
url URL no yes url of this object
product_id line 100 yes no has to be unique and correspond to an id of the product id from a client's accounting application
barcode line 100 yes no bar code
name line 200 yes no product name
category_id line 100 yes no category identifier. Has to correspond to category_id form the Catalog of product categories (see.p.5)
category_url URL no yes product category url
unit_id line 50 yes no measurement units identifier. Has to correspond to unit_id form Catalog of measurement units (see.p.7)
unit_url URL no yes measurement units url
markers JSON no yes additional characteristics of products (weight, color, set and others)

9.2. Available commands

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

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

9.2.1. GET /products/ - to receive one page of a collection.

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

Suffixes:

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

Parameters:

  • 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}
  • category_id={n} - to show only a product from a category with category_id={n}
  • search = text - to show only the objects, which name contain "text"
  • ordering=name - to sort fields alphabetically (ascending)
  • ordering = -name - to sort fields in reverse order

Server's response:

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/products/.json/?search=unknown-string

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

Example of a 2-element collection:

GET http://api.datawiz.io/api/v1/products/?format=json&page_size=2:

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"count": 8,
"next": "http://api.datawiz.io/api/v1/products/?page=2&page_size=2",
"previous": null,
"results": [
{
"url": "http://api.datawiz.io/api/v1/products/proba/",
"product_id": "proba",
"barcode": null,
"name": "\" La Festa \ "cappuccino GV 12,5 * 10 * 8pieces (natural/instant) (cream",
"category_id": "2",
"category_url": "http://api.datawiz.io/api/v1/categories/2/",
"unit_id": "2",
"unit_url": "http://api.datawiz.io/api/v1/units/2/"
"markers": {"color": "red",  "size":"2 inch"}
},
{
"url": "http://api.datawiz.io/api/v1/products/1000/",
"product_id": "1000",
"barcode": null,
"name": ""La Festa" cappuccino GV 12,5х10х8pieces (natural/instant) nut"
"category_id": "2",
"category_url": "http://api.datawiz.io/api/v1/categories/2/",
"unit_id": "2",
"unit_url": "http://api.datawiz.io/api/v1/units/2/"
"markers": {"color": "red",  "size":"2 inch"}
}
]
}

Error report:

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

9.2.2. POST /products/ - to add one object to the Catalog of products

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

Suffixes:

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

Parameters:

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

Request data:

A request contains a JSON-object of dictionary type describing a new item. All the fields are important: product_id, category_id, name, unit_id.

unit_id field can have null value . The order of fields is not important.

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

{
     "product_id": "123456-TEST", 
     "barcode": null, 
     "name": "New Product",
     "category_id": "232",
     "unit_id": "2",
     "markers": {"power": "50W"}
}

Server's response:

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/products/123456-TEST/ 
Allow: GET, POST, HEAD, OPTIONS 
{
"updated": 0,
"inserted": 1
}

Conditions and constraints:

  • If an object with product_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 category with an indicated category_id
  • One can not add to server an object if there is no measurement unit with an indicated unit_id
  • The name field can not be empty.

Error report:

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.

Remark. Each error report is a collection (array) of lowercase characters:

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." 
     ] 
}

9.2.3. POST /products/ - bulk copying of objects to the Catalog of products

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

Suffixes:

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

Parameters:

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

Request data:

The request contains a JSON object of list type with one or more objects describing new product. Sending list type objects to server increases the speed of work.

Example of a request to add three new objects to the Catalog of products

POST http://api.datawiz.io/api/v1/products/.json

[
    {
        "product_id": "TEST-PRODUCT-0014", 
        "barcode": "null", 
        "name": "French bread regular", 
        "category_id": "2", 
        "unit_id": "2"
        "markers": {"color": "red",  "size":"6 inch"}
    },
    {
        "product_id": "TEST-PRODUCT-0015", 
        "barcode": "null", 
        "name": "Milk 3.2%", 
        "category_id": "2", 
        "unit_id": "2"
        "markers": {"color": "red",  "size":"1 inch"}
    },
    {
        "product_id": "TEST-PRODUCT-0016", 
        "barcode": "null", 
        "name": "Bread 1quality", 
        "category_id": "2", 
        "unit_id": "2"
        "markers": {"color": "red",  "size":"4 inch"}
    }
]

Server's response:

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": 0,
"inserted": 3
}

Conditions and constraints:

  • If an object with product_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 category with an indicated category_id
  • One can not add to server an object if there is no measurement unit with an indicated unit_id
  • The name field can not be empty.
  • In markers field there can not be any nested structures (arrays and nested objects)

Error report:

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 (category_id field of the second object has a mistake):

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

As you can see, the error occurred in the second object in category_id field. An error reason is also included here.

9.2.4. OPTIONS /products/ - meta information about an object structure

The following JSON structure returns at this command:

OPTIONS /api/v1/products/

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"name": "Product List",
"description": "Products",
"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
},
"product_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 100
},
"barcode": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 100
},
"name": {
"type": "string",
"required": true,
"read_only": false,
"label": "name",
"max_length": 200
},
"category_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 100
},
"category_url": {
"type": "field",
"required": false,
"read_only": true
},
"unit_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 50
},
"unit_url": {
"type": "field",
"required": false,
"read_only": true
},
"markers": {
"type": "field",
"required": false,
"read_only": false,
"label": "Markers"
},
}
}
}

10. Resource products/{id} - particular object from the Catalog of products

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

10.1. Object structure:

Field name Field type Size Required Read only Remark
url URL no yes url of this object
product_id line 100 100 yes no has to be unique and correspond to an id of the product id from a client's accounting application
barcode line date/td> no bar code
name line 200 yes no product name
category_id line 100 yes no category identifier. Has to correspond to category_id form the Catalog of product categories (see.p.5)
category_url URL no yes product category url
unit_id line 50 yes no measurement units identifier. Has to correspond to unit_id form the Catalog of measurement units (see.p.7)
unit_url URL no yes measurement units url
markers JSON no yes additional characteristics of products (weight, color, set and others)

10.2. Available commands:

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

  • GET - to get an object with product_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 form the Catalog of products
  • OPTIONS - meta information about an object structure
  • HEAD - similar to GET, but you receive only a heading of a respond

10.2.1. GET - to get an object with product_id = {id}

Command type: GET http://api.datawiz.io/api/v1/products/12345 - to get an object with product_id=12345

Suffixes:

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

Parameters:

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

Server's response:

If one sends to server GET /products/{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/products/17786/.json:

{
     "url": "http://api.datawiz.io/api/v1/products/17786/", 
     "product_id": "17786", 
     "barcode": "null",
     "name": "\" La Festa \ "cappuccino GV 12,5 * 10 * 8pieces (natural/instant) (cream"
     "category_id": "222",
     "category_url": "http://api.datawiz.io/api/v1/categories/222/", 
     "unit_id": "2", 
     "unit_url": "http://api.datawiz.io/api/v1/units/2/",
     "markers": {"power": "50W"}
}

Error report:

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

10.2.2. PUT /products /{id}/ - to replace an object on server with a new object

This request works as two sequential requests:

  1. to delete an object with old product_id = {id} (DELETE)

  2. to create a new object with new product_id (POST)

Command type: PUT http://api.datawiz.io/api/v1/products/12345/.json - to replace the object with product_id=12345 into another

Suffixes:

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

Parameters:

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

Request data:

Request contains JSON object with new value of an object

All the fields are important: product_id, name, category_id and unit_id.

Example of a request to replace an object in the Catalog of products.

PUT http://api.datawiz.io/api/v1/products/123456-TEST/.json

{
     "product_id": "123456-NEW-ID", 
     "barcode": "null",
     "name": "Another Name",
     "category_id": "222",
     "unit_id": "2",
     "markers": {"power": "50W"}
}

Server's response:

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

Remark. If the product_id field 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, PUT, DELETE, HEAD, OPTIONS, PATCH 
{
"url": "http://api.datawiz.io/api/v1/products/123456-NEW-ID/",
"product_id": "123456-NEW-ID",
"barcode": "null",
"name": "Another Name",
"category_id": "222",
"category_url": "http://api.datawiz.io/api/v1/categories/222/",
"unit_id": "2",
"unit_url": "http://api.datawiz.io/api/v1/units/2/",
"markers": {"power": "50W"}
}

Conditions and constraints:

  • If an object with product_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 category with an indicated category_id
  • One can not add to server an object if there is no measurement unit with an indicated unit_id
  • The name field can not be empty.

Remark. Replacement of this object will result in all receipts where the product is mentioned. name and product_id will also be changed into new ones.

Error report:

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." 
     ] 
}

10.2.3. PATCH /products/{id}/ - to change the value of particular fields of an object

PATCH command is used to change particular fields of an object. PATCH is similar to PUT, but here you can state not only all objects, but the fields that have to be changed.

Command type: PATCH http://api.datawiz.io/api/v1/products/12345/.json - to remove particular fields of the object with product_id = 12345 into other ones

Suffixes:

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

Parameters:

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

Request data:

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

All the fields are important: product_id, name, category_id and unit_id.

Example of a request to change the value of name field for an object with product_id=123456-NEW-ID in the Catalog of products:

PUT http://api.datawiz.io/api/v1/products/123456-NEW-ID/.json

{
     "name": "Corrected product name" 
}

Server's response:

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

Remark. If the product_id field 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/products/123456-NEW-ID/",
"product_id": "123456-NEW-ID",
"barcode": "null",
"name": "Corrected product name"
"category_id": "222",
"category_url": "http://api.datawiz.io/api/v1/categories/222/",
"unit_id": "2",
"unit_url": "http://api.datawiz.io/api/v1/units/2/"
"markers": {"power": "50W"}
}

Conditions and constraints:

  • If an object with product_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 category with an indicated category_id
  • One can not add to server an object if there is no measurement unit with an indicated unit_id
  • The name field can not be empty.

Remark. Replacement of this object will result in all receipts where the product is mentioned. name and product_id will also be changed into new ones.

Error report:

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." 
     ] 
}

10.2.4. DELETE /products/{id}/ - delete from the Catalog of products

DELETE command is used to extract a particular product from the Catalog of products

Command type: DELETE http://api.datawiz.io/api/v1/products/12345/ - delete with product_id = 12345

Suffixes:

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

Parameters:

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

Request data:

The request doesn't have to contain anything.

Server's response:

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

Constraints:

  • Impossible to delete a product used in receipts.

Error report:

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

10.2.5. OPTIONS /products/{id}/ - meta information about an object structure

The following JSON structure returns at this command:

OPTIONS /api/v1/products/123456-NEW-ID/

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
{
"name": "Product Instance",
"description": "Products",
"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
},
"product_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 100
},
"barcode": {
"type": "string",
"required": true,
"read_only": false,
"max_length":
},
"name": {
"type": "string",
"required": true,
"read_only": false,
"label": "name",
"max_length": 200
},
"category_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 100
},
"category_url": {
"type": "field",
"required": false,
"read_only": true
},
"unit_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 50
},
"unit_url": {
"type": "field",
"required": false,
"read_only": true
},
"markers": {
"type": "field",
"required": false,
"read_only": false,
"label": "Markers"
}
}
}
}
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️