Rest API List of sales - datawizio/pythonAPI GitHub Wiki

25. Resource /sale/ (List of sales, Collection)

List of sales - is a list with all recent or past sales of a client's shop network. With the help of /sale/ resource you can get read_only access to the list of sales.

25.1.1. Sale object structure:

Field name Field type Size Required Read only Remark
url URL no yes url of this object
sale_id line 200 yes no sales identifier
shops list yes no shop or shops where the sale exists or existed
name line 100 yes no sale name
description line yes no sale description
date_from date yes no date when the sale starts
date_to date yes no date when the sale ends
products list yes no products on proomo

25.1.2. Products object structure

Field name Field type Size Required Read only Remark
url URL no yes url of this object
product_id line yes no product
product_url URL no yes url of this object

25.2. Available commands

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

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

25.2.1. GET /sale/ - to receive one page of a collection. Command type: GET http://api.datawiz.io/api/v1/sale

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 name 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).

An example of an empty collection returned by server:

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

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

Example of a 2-element collection:

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

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS
{
    "count": 3, 
    "next": "http://api.datawiz.io/api/v1/sale/?page=2&page_size=2&format=api", 
    "previous": null, 
    "results": [
         {
            "url": "http://api.datawiz.io/api/v1/sale/SALE-ID-G10Y-P0T0-X5L9/",
            "shops": [
                "1ca1a667-c335-11e5-b11b-000c29883704",
                "16aa5faa-26e0-11e5-9d5b-000c29883704",
                "0f9e8ac0-3cd5-11e5-9d5b-000c29883704",
                "6d153e30-5076-11e5-ab16-000c29883704",
                "e6491ef8-5709-11e5-ab16-000c29883704",
                "dd582d89-8889-11e5-a127-000c29883704",
                "9856d0f5-0929-11e5-80d8-7054d2c57800"
            ],
            "sale_id": "SALE-1",
            "name": "test",
            "description": "",
            "date_from": "2/22/2016",
            "date_to": "2016-03-10",
            "products": []
        },
        {
            "url": "http://api.datawiz.io/api/v1/sale/SALE-ID-ALFK-NLKS-EG9G/",
            "shops": [
                "6d153e30-5076-11e5-ab16-000c29883704",
                "0f9e8ac0-3cd5-11e5-9d5b-000c29883704",
                "e6491ef8-5709-11e5-ab16-000c29883704",
                "16aa5faa-26e0-11e5-9d5b-000c29883704",
                "dd582d89-8889-11e5-a127-000c29883704",
                "1ca1a667-c335-11e5-b11b-000c29883704",
                "9856d0f5-0929-11e5-80d8-7054d2c57800"
            ],
            "sale_id": "SALE-2",
            "name": "datawiz.io",
            "description": "gfdgdf",
            "date_from": "2/1/2016",
            "date_to": "3/9/2016",
            "products": [
                {
                    "url": "http://api.datawiz.io/api/v1/sale/SALE-ID-ALFK-NLKS-EG9G/products/c9e89a8e-1cd9-11e5-b5eb-000c29883704/",
                    "product_id": "c9e89a8e-1cd9-11e5-b5eb-000c29883704",
                    "product_url": "http://api.datawiz.io/api/v1/product/c9e89a8e-1cd9-11e5-b5eb-000c29883704/"
                },
                {
                    "url": "http://api.datawiz.io/api/v1/sale/SALE-ID-ALFK-NLKS-EG9G/products/d840c496-2195-11e5-8f96-000c29883704/",
                    "product_id": "d840c496-2195-11e5-8f96-000c29883704",
                    "product_url": "http://api.datawiz.io/api/v1/product/d840c496-2195-11e5-8f96-000c29883704/"
                }
    ]
}

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 string http.response.content:

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

25.2.2 POST /sale/ - to add one or several sales

Command type: POST http://api.datawiz.io/api/v1/sale/?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 sale.

Important fields: shops, name, description, date_from, date_to and products. The sequence of fields is not important.

Example of request to add one new sale:

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

{
    "shops": ["Shop1", "Shop2"],
    "sale_id": "SALE_1",
    "name": "Milk", 
    "description": "milk_on_sale", 
    "date_from": "2-02-2015", 
    "date_to": "2-03-2015", 
    "products": ["Kozak_milk"], 
}

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

Conditions and constraints:

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

25.2.3. OPTIONS /sale/ - meta information about an object structure

The following JSON structure returns at this command:

OPTIONS /api/v1/sale/

HTTP 200 OK 
Content-Type: application/json 
Vary: Accept 
Allow: GET, HEAD, OPTIONS 
{
"name": "Sale List",
"description": "",
"renders": [
"application/json",
"text/html"
],
"parses": [
"application/json",
"application/x-www-form-urlencoded",
"multipart/form-data"
],
"actions": {
"POST": {
"url": {
"type": "string",
"required": false,
"read_only": true,
"label": "Url"
},
"shops": {
"type": "list",
"required": true,
"read_only": false,
"label": "Shops",
"child": {
"type": "string",
"required": true,
"read_only": false
}
},
"name": {
"type": "string",
"required": true,
"read_only": false,
"label": "Name",
"max_length": 100
},
"sale_id": {
"type": "string",
"required": true,
"read_only": false,
"label": "Sale id",
"max_length": 200
},
"description": {
"type": "string",
"required": true,
"read_only": false,
"label": "Description"
},
"date_from": {
"type": "date",
"required": true,
"read_only": false,
"label": "Date from"
},
"date_to": {
"type": "date",
"required": true,
"read_only": false,
"label": "Date to"
},
"products": {
"type": "field",
"required": true,
"read_only": false,
"label": "Products",
"child": {
"type": "nested object",
"required": true,
"read_only": false,
"children": {
"url": {
"type": "field",
"required": false,
"read_only": true,
"label": "Url"
},
"product_id": {
"type": "integer",
"required": true,
"read_only": false,
"label": "Product id"
},
"product_url": {
"type": "integer",
"required": false,
"read_only": true,
"label": "Product url"
}
}
}
}
}
}
}
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️