Rest API Catalog of cashiers - datawizio/pythonAPI GitHub Wiki

13. Resource /cashiers/ (Catalog of cashiers, Collection)

Catalog of cashiers - is a general list of cashiers of a shop network (not linked to one particular shop). With the help of /cashiers/ resource one can get access to the list of cashiers and add new data to a catalog.

13.1. Object structure:

Field name Field type Size Required Read only Remark
url URL no yes url of this object
cashier_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 full name of a cashier

13.2. Available commands:

The following commands are used with the /cashiers/ 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 Cashiers
  • OPTIONS - meta information about an object structure
  • HEAD - similar to GET, but you receive only a heading of a response

13.2.1. GET /cashiers/ - to receive one page of a collection.

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

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 cashier_id

Server's response:

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

An example of an empty collection returned to a request:

GET http://api.datawiz.io/api/v1/cashiers/.json/?search=unknown-string

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

Example of a 2-element collection:

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

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"count": 5,
"next": "http://api.datawiz.io/api/v1/cashiers/?page=2&page_size=2",
"previous": null,
"results": [
{
"url": "http://api.datawiz.io/api/v1/cashiers/001/",
"cashier_id": "001",
"name": "Cashier #1"
},
{
"url": "http://api.datawiz.io/api/v1/cashiers/002/",
"cashier_id": "002",
"name": "Cashier #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"
}

13.2.2. POST /cashiers/ - to add one object to the Catalog of cashiers

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

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

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

{
    "cashier_id": "20", 
    "name": "Cashier #20" 
}

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

Conditions and constraints:

  • If an object with cashier_id already exists on the server, the request will replace the object on server without notification.
  • 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.

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

13.2.3. POST /cashiers/ - bulk copying of objects to the Catalog of cashiers

Command type: POST http://api.datawiz.io/api/v1/cashiers/?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 (json-dictionary, see p.13.2.2), 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 cashiers

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

[
    {
        "cashier_id": "001", 
        "name": "Cashier #1"
    },
    {
        "cashier_id": "002", 
        "name": "Cashier #2"
    },
    {
        "cashier_id": "003", 
        "name": "Cashier #1"
    }
]

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 cashier_id already exists on the server, the request will replace the object on server without notification.
  • 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 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 (name field of the second object is not filled):

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

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

13.2.4. OPTIONS /cashiers/ - meta information about an object structure

The following JSON structure returns at this command:

OPTIONS /api/v1/cashiers/

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"name": "Cashier List",
"description": "this is my Cashier text. You can see this text on the REST-page",
"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
},
"cashier_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 50
},
"name": {
"type": "string",
"required": true,
"read_only": false,
"label": "name",
"max_length": 100
}
}
}
}

14. Resource /cashiers/{id} - particular object from the Catalog of cashiers

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

14.1. Object structure:

Field name Field type Size Required Read only Remark
url URL no yes url of this object
cashier_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 full name of a cashier

14.2. Available commands:

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

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

14.2.1. GET - to get an object with cashier_id={id}

Command type: GET http://api.datawiz.io/api/v1/cashiers/003 - to receive an object with cashier_id=003

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 /cashiers/{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/cashiers/003/.json:

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
{
"url": "http://api.datawiz.io/api/v1/cashiers/003/",
"cashier_id": "003",
"name": "Cashier #3"
}

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

14.2.2. PUT /cashiers/{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 cashier_id = {id} (DELETE)

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

Command type: PUT http://api.datawiz.io/api/v1/cashiers/003/.json - to replace the object with cashier_id="003" 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: cashier_id і name.

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

PUT http://api.datawiz.io/api/v1/cashiers/003/.json

{
    "cashier_id": "0034", 
    "name": "Cashier #003 (Another Name)" 
}

Here, the name field is going to be changed. It should be stated that when changing the value of a key field (identifier, in this case - cashier_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 cashier_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/cashiers/003/",
"cashier_id": "003",
"name": "Cashier #003 (Another Name)"
}

Constraints:

  • If an object with cashier_id already exists on the server, the request will replace the object on server without notification.
  • 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.

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

14.2.3. PATCH /cashiers/{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 the fields that have to be changed.

Command type: PATCH http://api.datawiz.io/api/v1/cashiers/5/.json - to remove particular fields of the object with cashier_id=5 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 particular field of an object.

All the fields are important: cashier_id, name, packed, pack_capacity.

Example of a request to change the value of name fields for an object with cashier_id=005 in the Catalog of cashiers:

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

{
    "name": "Cashier #5 (new 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 cashier_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/cashiers/005/",
"cashier_id": "005",
"name": "Cashier #5 (new name)"
}

Constraints:

  • If an object with cashier_id already exists on the server, the request will replace the object on server without notification.
  • 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." 
     ] 
}

14.2.4. DELETE /cashiers/{id}/ - delete from the Catalog of cashiers

DELETE command is used to extract a particular object from the Catalog of cashiers.

Command type: DELETE http://api.datawiz.io/api/v1/cashiers/100/ - delete an object with cashier_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:

  • Impossible to delete an entry about a cashier 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"
}

14.2.5. OPTIONS /cashiers/{id}/ - meta information about an object structure

The following JSON structure returns at this command:

OPTIONS /api/v1/cashiers/100/

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
{
"name": "Cashier Instance",
"description": "this is my Cashier text. You can see this text on the REST-page",
"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
},
"cashier_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 50
},
"name": {
"type": "string",
"required": true,
"read_only": false,
"label": "name",
"max_length": 100
}
}
}
}
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️