Rest API Catalog of measurement units - datawizio/pythonAPI GitHub Wiki

7. Resource `/units/` (Catalog of measurement units, Collection)

Catalog of measurement units - is a list of measurement units of products (pieces, kilos, packages, and others) With the help of /units/ resource one can get access to the list of measurement units and add new units to a catalog.

7.1. Object structure:

Field name	Field type	Size	Required	Read only	Remark
`url`	URL		no	yes	url of this object
`unit_id`	line	50	yes	no	has to be unique and correspond to an `id` of the measurement units from a client's accounting application
`name`	line	100	yes	no	measurement unit name

7.2. Available commands

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

GET - to receive one page on a collection
POST - to add a measurement unit or a list of measurement units to the Catalog of measurement units
OPTIONS - meta information about an object structure
HEAD - similar to GET, but you receive only a heading of a response

7.2.1. `GET /units/` - to receive one page of a collection.

Command type: GET http://api.datawiz.io/api/v1/units/ Suffixes:

.json - to receive a response from a server in JSON format
.api - to receive a response 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}
search = {substring} - to show only the objects, which name contain "{substring}"
ordering=name|identifier - to sort fields alphabetically (ascending)
ordering = -name | -identifier - to sort fields in the reverse order Remark: identifier - to sort according to the field units_id

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

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

Example of a 2-element collection:

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

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"count": 39,
"next": "http://api.datawiz.io/api/v1/units/?page=2&amp;page_size=2&amp;format=api",
"previous": null,
"results": [
{
"url": "http://api.datawiz.io/api/v1/units/1-1/",
"unit_id": "1-1",
"name": "Cash register 1",
"shop_id": "1",
"shop_url": "http://api.datawiz.io/api/v1/shops/1"
},
{
"url": "http://api.datawiz.io/api/v1/units/2-1/",
"unit_id": "2-1",
"name": "Cash register 1",
"shop_id": "2",
"shop_url": "http://api.datawiz.io/api/v1/shops/2"
}
]
}

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

7.2.2. `POST /units/` - to add one object to the Catalog of measurement units

Command type: POST http://api.datawiz.io/api/v1/units/?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: unit_id, name. The order of fields is not important.

Example of a request to add one new object to the Catalog of measurement units:

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

{
    "unit_id": "2", 
    "name": (kg)", 
}

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

Conditions and constraints:

If an object with unit_id already exists on the server, the request will replace the object on server without notification.
The name field can not be empty.
The name field has to be unique (the server shouldn't contain an object with the same name).

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

7.2.3. `POST /units/` - bulk copying of objects to the Catalog of measurement units

Command type: POST http://api.datawiz.io/api/v1/units/?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 measurement unit. Sending list type objects to server increases the speed of work.

Example of a request to add three new objects to the Catalog of measurement units

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

[
    {
        "unit_id": "2", 
        "name": (kg)", 
    }, 
    {
        "unit_id": "4", 
        "name": "pack 10pcs"
    },
    {
        "unit_id": "4", 
        "name": "pcs"
    }
]

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": 1,
"inserted": 2
}

Conditions and constraints:

If an object with unit_id already exists on the server, the request will replace the object on server without notification.
The name field can not be empty.
The name field has to be unique (the server shouldn't contain an object with the same name).

Error report:

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

Example of server's response with an error ( name field of the second object is not unique):

HTTP 400 BAD REQUEST
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
[
{},
{
"name": [
"The name 'pack 10pcs' is already used for object with unit_id=4"
]
},
{}
]

As you can see, the error occurred in the second object in name field.

An error reason is also indicated here.

7.2.4. `OPTIONS /units/` - meta information about an object structure

The following JSON structure returns at this command:

OPTIONS /api/v1/units/

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"name": "Unit List",
"description": "Units",
"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
},
"unit_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 50
},
"name": {
"type": "string",
"required": true,
"read_only": false,
"label": "name",
"max_length": 100
}
}
}
}

8. Resource `units/{id}` - particular object from the Catalog of measurement units

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

8.1. Object structure:

Field name	Field type	Size	Required	Read only	Remark
`url`	URL		no	yes	url of this object
`unit_id`	line	50	yes	no	has to be unique and correspond to an `id` of the measurement units from a client's accounting application
`name`	line	100	yes	no	measurement unit name

8.2. Available commands:

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

GET - to get an object with unit_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 measurement units an object with unit_id={id}
OPTIONS - meta information about an object structure
HEAD - similar to GET, but you receive only a heading of a response

8.2.1. `GET` - to get an object with `unit_id={id}`

Command type: GET http://api.datawiz.io/api/v1/units/4 - to get an object withunit_id=4

Suffixes:

.json - to receive a response from a server in JSON format
.api - to receive a response 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 /units/{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/units/4/.json:

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
{
"url": "http://api.datawiz.io/api/v1/units/4/",
"unit_id": "4",
"name": "pcs"
}

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

8.2.2. `PUT /units/{id}/` - to replace an object on server with a new object

This request works as two sequential requests:

to delete an object with old unit_id = {id} (DELETE)
to create a new object with new unit_id (POST)

Command type: PUT http://api.datawiz.io/api/v1/units/4/.json - to replace the object with unit_id="4" into another one

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: unit_id, name.

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

PUT http://api.datawiz.io/api/v1/units/4/.json

{
    "unit_id": "44", 
    "name": "pcs"
}
}

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

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 unit_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/units/5/",
"unit_id": "5",
"name": "pcs"
}

Constraints:

If an object with unit_id` already exists on the server, the request will replace the object on server without notification.
The name` field can not be empty.
The name` field has to be unique (the server shouldn't contain an object with the same name).

Error report:

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

8.2.3. PATCH /units/{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 an entire object, but only fields that have to be changed.

Command type: PATCH http://api.datawiz.io/api/v1/units/5/.json - to change particular fields of the object with з unit_id=5 into another 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: unit_id, name.

Example of a request to change the value of name fields for an object with unit_id=5 in the Catalog of measurement units:

PATCH http://api.datawiz.io/api/v1/units/5/.json

{
     "name": "pack.5pcs." 
}

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 unit_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/units/5/",
"unit_id": "5",
"name": "pack.5pcs."
}

Constraints:

If an object with unit_id already exists on the server, the request will replace the object on server without notification.
The name field can not be empty.
The name field has to be unique (the server shouldn't contain an object with the same name).

Error report:

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

8.2.4. `DELETE /units/{id}/` - delete from the Catalog of measurement units

DELETE command is used to extract a particular object from the Catalog of measurement units

Command type: DELETE http://api.datawiz.io/api/v1/units/100/ - to delete an object with unit_id=100

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:

You can not delete a measurement unit used in the Catalog of products

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

8.2.5. `OPTIONS /units/{id}/` - meta information about an object structure

The following JSON structure returns at this command:

OPTIONS /api/v1/units/1-100/
HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
{
"name": "Unit Instance",
"description": "Units",
"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
},
"unit_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 50
},
"name": {
"type": "string",
"required": true,
"read_only": false,
"label": "name",
"max_length": 100
}
}
}
}

Rest API Catalog of measurement units - datawizio/pythonAPI GitHub Wiki

7. Resource /units/ (Catalog of measurement units, Collection)

7.1. Object structure:

7.2. Available commands

7.2.1. GET /units/ - to receive one page of a collection.

7.2.2. POST /units/ - to add one object to the Catalog of measurement units

7.2.3. POST /units/ - bulk copying of objects to the Catalog of measurement units

7.2.4. OPTIONS /units/ - meta information about an object structure

8. Resource units/{id} - particular object from the Catalog of measurement units

8.1. Object structure:

8.2. Available commands:

8.2.1. GET - to get an object with unit_id={id}

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

8.2.4. DELETE /units/{id}/ - delete from the Catalog of measurement units

8.2.5. OPTIONS /units/{id}/ - meta information about an object structure

⚠️ **GitHub.com Fallback** ⚠️

7. Resource `/units/` (Catalog of measurement units, Collection)

7.2.1. `GET /units/` - to receive one page of a collection.

7.2.2. `POST /units/` - to add one object to the Catalog of measurement units

7.2.3. `POST /units/` - bulk copying of objects to the Catalog of measurement units

7.2.4. `OPTIONS /units/` - meta information about an object structure

8. Resource `units/{id}` - particular object from the Catalog of measurement units

8.2.1. `GET` - to get an object with `unit_id={id}`

8.2.2. `PUT /units/{id}/` - to replace an object on server with a new object

8.2.4. `DELETE /units/{id}/` - delete from the Catalog of measurement units

8.2.5. `OPTIONS /units/{id}/` - meta information about an object structure

⚠️ GitHub.com Fallback ⚠️