Rest API. List of point of sale terminals for each shop - datawizio/pythonAPI GitHub Wiki

3. Resource /terminals/ (List of point-of-sale terminals for each shop, Collection)

List of point-of-sale terminals - is a list of cash registers of each shop of the retail network. With the help of /terminals/ resource you can get access to the list of point-of-sale terminals and add new terminals to a Catalog.

3.1. Object structure:

Field name Field type Size Mandatory Read only Remarks
url URL no yes url of this object
terminal_id line 50 yes no has to be unique and correspond to an id of the terminal from a client's accounting application
shop_id line 50 yes no code of the shop from a /shops/ directory (see p.1)
name line 100 yes no name (or code) of a point-of-sale terminal, identifying it in a particular shop
shop_url URL no yes URL of a shop

3.2. Available commands

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

  • GET - to receive one page on a collection
  • POST - to add a new terminal to the list of poin-of-sale terminals
  • OPTIONS - meta information about an object structure
  • HEAD - similar to GET, but you receive only a heading of an answer

3.2.1. GET /terminals/ - to receive one page of a collection.

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

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}
  • shop_id={n} - to show the terminals in the shop with id={n}
  • search = {substring} - to show only the objects, which name contains "{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 fieldterminal_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/terminals/.json/?search=unknown-shop_id

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

Example of a 2-element collection: GET http://api.datawiz.io/api/v1/terminals/?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/terminals/?page=2&page_size=2&format=api",
"previous": null,
"results": [
{
"url": "http://api.datawiz.io/api/v1/terminals/1-1/",
"terminal_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/terminals/2-1/",
"terminal_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"
}

3.2.2. POST /terminals/ - to add one object to the list of poin-of-sale terminals

Command type: POST http://api.datawiz.io/api/v1/terminals/?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 three fields are important: terminal_id, shop_id and name. The sequence of fields is not important.

Example of a request to add one new object to the list of point-of-sale terminals: POST http://api.datawiz.io/api/v1/terminals/.json

{
     "terminal_id": "1-4",
     "shop_id": "1",
     "name": "New terminal"
}

Server's response:

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

Example of a server's response:

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

Conditions and constraints:

  • If an object with terminal_id already exists on the server, the request will replace the object on the server without notification.
  • One can not add to server an object if there is no shop with an indicated shop_id
  • The name field can not be empty.
  • The name field has to be unique within one shop.

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

3.2.3. POST /terminals/ - bulk copying of objects to the List of point-of-sale terminals

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

Example of a request to add three new objects to the list of point-of-sale terminals: POST http://api.datawiz.io/api/v1/terminals/.json

[
   {
     "terminal_id": "1-4",
     "shop_id": "1",
     "name": "Terminal 4",
   },
   {
     "terminal_id": "2-1",
     "shop_id": "2",
     "name": "Cash register 1", 
   },
   {
     "terminal_id": "2-2",
     "shop_id": "2",
     "name": "Cash register 2",
   }
]

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 terminal_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 shop with an indicated shop_id
  • The name field can not be empty.
  • The name field has to be unique within one shop. 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.

Remark. Example of server's response with an error ( shop_id field of the second object has a mistake):

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

As you can see, the error occurred in the second object in shop_id field. There is also an error reason indicated.

3.2.4. OPTIONS /terminals/ - meta information about an object structure

The following JSON structure returns at this command:

OPTIONS /api/v1/terminals/
HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"name": "Terminal List",
"description": "Terminals",
"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
},
"terminal_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 50
},
"name": {
"type": "string",
"required": true,
"read_only": false,
"label": "name",
"max_length": 100
},
"shop_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 50
},
"shop_url": {
"type": "field",
"required": false,
"read_only": true
}
}
}
}

4. Resource terminals/{id} - particular object from the List of point-of-sale terminals

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

4.1. Object structure:

Field name Field type Size Mandatory Read only Remarks
url URL no yes url of this object
terminal_id line 50 yes no has to be unique and correspond to an id of the terminal from a client's accounting application
shop_id line 50 yes no code of the shop from a /shops/ directory (see p.1)
name line 100 yes no name (or code) of a point-of-sale terminal, identifying it in a particular shop
shop_url URL 100 no yes URL of a shop

4.2. Available commands

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

  • GET - to get an object with terminal_id={id}
  • PUT - to replace an object on server with a new object
  • PATCH - to change the value of particular field of an object
  • DELETE - to delete from the List of point-of-sale terminals an object with terminal_id={id}
  • OPTIONS - meta information about an object structure
  • HEAD - similar to GET, but you receive only a heading of an answer

4.2.1. GET - to get an object with terminal_id={id}

Command type: GET http://api.datawiz.io/api/v1/terminals/CAT11 - to get an object with terminal_id="CAT11"

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 /terminals/{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/terminals/1-1/.json:

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
{
"url": "http://api.datawiz.io/api/v1/terminals/1-1/",
"terminal_id": "1-1",
"name": "Cash register 1",
"shop_id": "1",
"shop_url": "http://api.datawiz.io/api/v1/shops/1"
}

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

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

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

Command type: PUT http://api.datawiz.io/api/v1/terminals/1-1/.json - to change the object with terminal_id="1-1" 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: A request contains JSON object with a new object value All three fields are important: terminal_id, shop_id and name.

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

PUT http://api.datawiz.io/api/v1/terminals/1-1/.json

{
     "terminal_id": "1-100", 
     "name": "Another Name",
     "shop_id": "1"
}

Here the fields terminal_id and name have to be changed. It should be stated that when changing the value of a key field(identifier, in this case - terminal_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 terminal_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/terminals/1-100/",
"terminal_id": "1-100",
"name": "Another Name",
"shop_id": "1",
"shop_url": "http://api.datawiz.io/api/v1/shops/1"
}

Constraints:

  • During a remove you can not state another terminal_id if there already exists an object with the same terminal_id.
  • shop_id field has to contain a definite value form the List of shops (see p.1)
  • The name field can not be empty.
  • The name field has to be unique within one shop. 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. 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." 
     ] 
}

4.2.3. PATCH /terminals/{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/terminals/1-100/.json - to remove particular fields of the object with terminal_id=1-100 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 three fields are important: terminal_id, shop_id and name.

Example of a request to change the value of name field for an object with terminal_id=1-100 in the List of point-of-sale terminals:

PATCH http://api.datawiz.io/api/v1/terminals/1-100/.json

{
     "name": "Terminal #100" 
}

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 terminal_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/terminals/1-100/",
"terminal_id": "1-100",
"name": "Terminal #100",
"shop_id": "1",
"shop_url": "http://api.datawiz.io/api/v1/shops/1"
}

Constraints:

  • During a remove you can not state another terminal_id if there already exists an object with the same terminal_id.
  • shop_id field has to contain a definite value form the List of shops (see p.1)
  • The name field can not be empty.
  • The name field has to be unique within one shop.

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

4.2.4. DELETE /terminals/{id}/ - to delete from the List of point-of-sale terminals

DELETE command is used to extract a particular object from the List of point-of-sale terminals

Command type: DELETE http://api.datawiz.io/api/v1/terminals/1-100/ - delete an object with terminal_id=1-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 a terminal 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"
}

4.2.5.OPTIONS /terminals/{id}/ - meta information about an object structure

The following JSON structure returns at this command:

OPTIONS /api/v1/terminals/1-100/
HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
{
"name": "Terminal Instance",
"description": "my Terminal doc",
"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
},
"terminal_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 50
},
"name": {
"type": "string",
"required": true,
"read_only": false,
"label": "name",
"max_length": 100
},
"shop_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 50
},
"shop_url": {
"type": "field",
"required": false,
"read_only": true
}
}
}
}
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️