Rest API Shops list - datawizio/pythonAPI GitHub Wiki

List of shops - it is a list containing shop names of the client's network and corresponding identifiers. With the help of /shops/ resource you can get "read only" access to the list of shops. You can not delete any shop using REST API. If you need to add or delete a shop at the service, please contact the service administrator.

To manage the /shops/ resource, the following commands are used:

• GET - to receive one page of a collection
• OPTIONS - meta information about an object structure
• HEAD - similar to GET, but you receive only a heading of an answer

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

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 = text - to show only the objects, which names contain "text"
• ordering = name | identifier - to sort fields alphabetically (ascending)
• ordering = -name | -identifier - to sort fields in the reverse order

Server's response:

The "collection" object consists of four fields (count, next, previous, results). Example of an empty collection returned to a request:

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

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

Example of a 2-element collection: GET http://api.datawiz.io/api/v1/shops/?format=api&page_size=2:

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS
{
    "count": 11, 
    "next": "http://api.datawiz.io/api/v1/shops/?page=2&page_size=2&format=api", 
    "previous": null, 
    "results": [
        {
            "url": "http://api.datawiz.io/api/v1/shops/3", 
            "shop_id": "3", 
            "name": "Shop 1"
            "address": "address Shop 1" 
            "longitude": "123"         
            "latitude": "123"
        }, 
        {
            "url": "http://api.datawiz.io/api/v1/shops/2", 
            "shop_id": "2", 
            "name": "Shop 2"
            "address": "address Shop 1" 
            "longitude": "123"         
            "latitude": "123"
        }
    ]
}

Error report:

In case of an error, server returns a response with a corresponding status and an error report in detail key and/or in field http.response.content:

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

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

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

Request data: A request contains a JSON-object of dictionary type describing a new shop. Important fields: shop_id and name. The sequence of fields is not important.

Example of a request to add one new shop: POST http://api.datawiz.io/api/v1/shops/.json

{
    "shop_id": "124", 
    "name": "Storage facility at Oleksandrova", 
    "address": "Oleksandrova 5A", 
}

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

Conditions and constraints:

• If an object with shop_id already exists on the server, the request will replace the object on the server without notification.
• The name field can not be empty.

Error report:

In case of an error, the 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." 
     ] 
}

The following JSON structure returns at this command:

OPTIONS /api/v1/shops/

HTTP 200 OK 
Content-Type: application/json 
Vary: Accept 
Allow: GET, HEAD, OPTIONS 
{
"name": "Shop List",
"description": "",
"renders": [
"application/json",
"text/html"
],
"parses": [
"application/json",
"application/x-www-form-urlencoded",
"multipart/form-data"
]
}

Using /shops/{id} resource, one can download a Shop object from the List of Shops on a server. To chose a particular object, one should change an {id} in the resource URL into an identifier of the existing object from shop_id field. The list of available objects and their identifiers can be received using GET /shops/ command (for more details see chapter 1). Resource /shops/ (list of shops, collection, read only)")

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

• GET - to get an object with shop_id = {id}
• OPTIONS - meta information about an object structure
• HEAD - similar to GET, but you receive only a heading of an answer

Command type: GET http://api.datawiz.io/api/v1/shops/12345 - to receive an object with shop_id = 12345

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

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS
{
"url": "http://api.datawiz.io/api/v1/shops/1",
"shop_id": "1",
"name": "Shop 1"
"address": "address Shop 1"
"longitude": "123"
"latitude": "123"
}

Error report: In case of an error, server returns a response with a corresponding status and an error report in detail key and/or in http.response.content field:

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

The following JSON structure returns at this command: OPTIONS /api/v1/shops/1/

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS
{
"name": "Shop Detail",
"description": "",
"renders": [
"application/json",
"text/html"
],
"parses": [
"application/json",
"application/x-www-form-urlencoded",
"multipart/form-data"
]
}