Rest API List of clients taking part in loyalty program - datawizio/pythonAPI GitHub Wiki

List of clients taking part in loyalty program - is a register of customers, who registered in loyalty program of the shop network. With the help of the list shop owners can study their customers, monitor frequency of their purchases, make sales promotions and others. With /loyalty/ resource one can get access to the list of clients taking part in loyalty program and add new participants to the list.

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

• GET - to receive one page on a collection
• POST - to add an entry or several entries to the List of clients taking part in loyalty program.
• OPTIONS - meta information about an object structure
• HEAD - similar to GET, but you receive only a heading of a response

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

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}
• is_male={True,False} - show only: True-male or False - female
• search = {substring} - to show only the objects, where strings client_name or cardno contain "{substring}"
• ordering=cardno|client_name|client_birthday|identifier - to sort strings alphabetically (ascending)
• ordering = cardno|client_name|client_birthday|-identifier - to sort strings in the reverse order

Remark: identifier - to sort according to the string loyalty_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/loyalty/.json/?search=unknown-string

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

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

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"count": 3,
"next": "http://api.datawiz.io/api/v1/loyalty/?page=2&page_size=2",
"previous": null,
"results": [
{
"url": "http://api.datawiz.io/api/v1/loyalty/3/",
"loyalty_id": "3",
"cardno": "33",
"discount": "15.00",
"client_name": "Mariya",
"client_birthday": "1982-11-17T00:00:00",
"is_male": false,
},
{
"url": "http://api.datawiz.io/api/v1/loyalty/2/",
"loyalty_id": "2",
"cardno": "22",
"discount": "10.00",
"client_name": "Vlad",
"client_birthday": "1976-05-12T00:00:00",
"is_male": true,
}
]
}

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

Command type: POST http://api.datawiz.io/api/v1/loyalty/?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. Important fields: loyalty_id, client_name, client_birthday. The order of fields is not important.

Example of request to add new object to the List of clients taking part in loyalty program:

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

{
    "loyalty_id": "3", 
    "cardno": "33", 
    "discount": "15", 
    "client_name": "Mariya", 
    "client_birthday": "1982-11-17", 
    "is_male": false, 
}

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

Conditions and constraints:

• If an object with loyalty_id already exists on the server, the request will replace the object on server without notification.
• Date format in client_birthday field should be: YYYY-MM-DD
• All other fields can be null

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 ( client_birthday field has a mistake):

HTTP 400 BAD REQUEST
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"client_birthday": [
"Date has wrong format. Use one of these formats instead: YYYY[-MM[-DD]], YYYY-MM-DD"
]
}

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

Example of request to bulk add 3 new object to the List of clients taking part in loyalty program: POST http://api.datawiz.io/api/v1/loyalty/.json

[
    {
        "loyalty_id": "10", 
        "cardno": "332", 
        "discount": "5", 
        "client_name": "Customer #1", 
        "client_birthday": "10/20/1970", 
        "is_male": true, 
    },
    {
        "loyalty_id": "11", 
        "cardno": "333", 
        "discount": "5", 
        "client_name": "Customer #2", 
        "client_birthday": "4/12/1994", 
        "is_male": false, 
    },
    {
        "loyalty_id": "12", 
        "cardno": "334", 
        "discount": "5", 
        "client_name": "Customer #3", 
        "client_birthday": "6/11/1985", 
        "is_male": false, 
    }
]

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 loyalty_id already exists on the server, the request will replace the object on server without notification.
• Date format in client_birthday field should be: YYYY-MM-DD
• All other fields can be null

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 response in case of an error:

HTTP 400 BAD REQUEST
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
[
{},
{},
{
"discount": [
"Enter a number."
]
}
]

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

The following JSON structure returns at this command:

OPTIONS /api/v1/loyalty/

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"name": "Loyalty List",
"description": "Loyalty",
"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
},
"loyalty_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 50
},
"cardno": {
"type": "string",
"required": false,
"read_only": false,
"label": "cardno",
"max_length": 20
},
"discount": {
"type": "decimal",
"required": false,
"read_only": false,
"label": "discount"
},
"client_name": {
"type": "string",
"required": false,
"read_only": false,
"label": "client name",
"max_length": 200
},
"client_birthday": {
"type": "date",
"required": true,
"read_only": false
},
"is_male": {
"type": "boolean",
"required": false,
"read_only": false,
"label": "is male"
}
}
}
}

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

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

• GET - to get an object with loyalty_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 form the List of clients taking part in loyalty program object with loyalty_id={id}
• OPTIONS - meta information about an object structure
• HEAD - similar to GET, but you receive only a heading of a response

Command type: GET http://api.datawiz.io/api/v1/loyalty/4 - to get an object with loyalty_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 /loyalty/{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/loyalty/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/loyalty/4/",
"loyalty_id": "4",
"cardno": "331",
"discount": "3.00",
"client_name": "Mariya Dyvna",
"client_birthday": "1986-09-01T00:00:00",
"is_male": false,
}

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

12.2.2. PUT /loyalty/{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 loyalty_id = {id} (DELETE)

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

Command type: PUT http://api.datawiz.io/api/v1/loyalty/4/.json - to replace the object with loyalty_id="4" 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

Only the field loyalty_id is important, all other fields can be null

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

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

{
    "url": "http://api.datawiz.io/api/v1/loyalty/4/", 
    "loyalty_id": "4", 
    "cardno": "331", 
    "discount": "4.00", 
    "client_name": "Mariya Dyvna", 
    "client_birthday": "9/1/1986", 
    "is_male": false, 
}

Here the discount string should be replaced. It should be stated that when changing the value of a key string (identifier, in this case - loyalty_id) the string 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 loyalty_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/loyalty/4/",
"loyalty_id": "4",
"cardno": "331",
"discount": "4.00",
"client_name": "Mariya Dyvna",
"client_birthday": "9/1/1986",
"is_male": false,
}

Constraints:

• If an object with loyalty_id already exists on the server, the request will replace the object on server without notification.
• Date format in client_birthday field should be: YYYY-MM-DD
• All other fields can be null

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 servers response for an error (field discount with number, field client_birthday - wrong data format):

HTTP 400 BAD REQUEST 
Content-Type: application/json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS
{
"discount": [
"Enter a number."
],
"client_birthday": [
"Date has wrong format. Use one of these formats instead: YYYY-MM-DD"
]
}

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/loyalty/5/.json - to remove particular fields of the object with loyalty_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

Only the field loyalty_id is important. All other fields can be null

Example of a request to change the value of the field discount for the object with loyalty_id=4:

PATCH http://api.datawiz.io/api/v1/loyalty/4/.json

{
    "discount": "5.00", 
}

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 loyalty_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/loyalty/4/",
"loyalty_id": "4",
"cardno": "331",
"discount": "5.00",
"client_name": "Mariya Dyvna",
"client_birthday": "1986-09-01T00:00:00",
"is_male": false,
}

Constraints:

• If an object with loyalty_id already exists on the server, the request will replace the object on server without notification.
• Date format in client_birthday field should be: YYYY-MM-DD
• All other fields can be null

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 ( client_birthday field has wrong data format):

HTTP 400 BAD REQUEST 
Content-Type: application/json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS
{
"client_birthday": [
"Date has wrong format. Use one of these formats instead: YYYY-MM-DD"
]
}

DELETE command is used to delete a particular object from the List of clients taking part in loyalty program.

Command type: DELETE http://api.datawiz.io/api/v1/loyalty/100/ - delete an object with loyalty_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 a measurement unit already 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"
}

The following JSON structure returns at this command:

OPTIONS /api/v1/loyalty/100/

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
{
"name": "Loyalty Instance",
"description": "Loyalty",
"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
},
"loyalty_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 50
},
"cardno": {
"type": "string",
"required": false,
"read_only": false,
"label": "cardno",
"max_length": 20
},
"discount": {
"type": "decimal",
"required": false,
"read_only": false,
"label": "discount"
},
"client_name": {
"type": "string",
"required": false,
"read_only": false,
"label": "client name",
"max_length": 200
},
"client_birthday": {
"type": "date",
"required": true,
"read_only": false
},
"is_male": {
"type": "boolean",
"required": false,
"read_only": false,
"label": "is male"
}
}
}
}