Skip to content

API

Jump to bottom
thergbway edited this page Apr 20, 2016 · 41 revisions

0. Response and error wrappers

All success and error responses are wrapped.
error_response:

{
    "error": JSON_ERROR_OBJECT
}

JSON_ERROR_OBJECT is explained on API errors page

success_response:

{
    "response": REST_API_METHOD_RESPONSE_OBJECT
}

REST_API_METHOD_RESPONSE_OBJECT is a response of the methods explained below.
Note: success_response can be empty if method returns an empty response e.g. delete methods

1. Token authentication

All methods that are not marked as no token needed must be executed with Token header presented. Token header must be filled with existing token that was taken after authentication step.
Exceptions: INVALID_ACCESS_TOKEN, NO_ACCESS_TOKEN

2. Authentification

2.1 User authentification

Note: no token needed

Request: POST /auth
Request body:

{
    !"vk_access_token": STRING,
    !"vk_user_id": INTEGER,
    !"ruber_app_id": INT,
    !"ruber_app_secret": STRING
}

Request headers:
Accept=application/json
Content-Type=application/json
Response:

{
    !"ruber_access_token": STRING,
    !"id": INT
}

Exceptions: INVALID_EXTERNAL_APP_CREDENTIALS

3 Orders

3.1 Add order

Request: POST /markets/{market_id}/orders
Request headers: Content-Type=application/json
Request body:

{
    !"title": STRING,
    "description": STRING,
    !"status": ENUM("WAITING", "PAID", "DONE", "CANCELLED"),
    "deadline_timestamp": LONG or NULL,
    !"customer": {
        !"name": STRING,
        !"phone": STRING,
        "vk_id": INTEGER or NULL
    },
    "shipment": {
        !"address": STRING,
        !"cost": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99"
    },
    "discount": {
        !"title": STRING,
        !"description": STRING,
        !"thumb_photo": URL e.g. "http://google.com/pic1",
        !"cost": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99"
    },
    !"item_replicas": [
        {
            !"title": STRING,
            !"description": STRING,
            !"thumb_photo": URL e.g. "http://google.com/pic1",
            !"price": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99",
            !"amount": INTEGER    
        },
        {
            !"title": STRING,
            !"description": STRING,
            !"thumb_photo": URL e.g. "http://google.com/pic1",
            !"price": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99",
            !"amount": INTEGER,
            !"vk_id": INTEGER    
        }
        ...        
    ]
}

Note: it is possible to place vk_item_replicas with vk_id specified
as well as usual item_replicas Response body:

{
    !"id": INTEGER,
    !"title": STRING,
    "description": STRING,
    !"status": ENUM("WAITING", "PAID", "DONE", "CANCELLED"),
    !"created_timestamp": LONG,
    !"deadline_timestamp": LONG or NULL,
    !"customer": {
        !"name": STRING,
        !"phone": STRING,
        !"vk_id": INTEGER or NULL
    },
    !"shipment": NULL or {
        !"address": STRING,
        !"cost": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99"
    },
    !"discount": NULL or {
        !"title": STRING,
        !"description": STRING,
        !"thumb_photo": URL e.g. "http://google.com/pic1",
        !"cost": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99"
    },
    !"item_replicas": [
        {
            !"id": INTEGER,
            !"title": STRING,
            !"description": STRING,
            !"thumb_photo": URL e.g. "http://google.com/pic1",
            !"price": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99",
            !"amount": INTEGER    
        },
        {
            !"id": INTEGER,
            !"title": STRING,
            !"description": STRING,
            !"thumb_photo": URL e.g. "http://google.com/pic1",
            !"price": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99",
            !"amount": INTEGER,
            !"vk_id": INTEGER    
        }
        ...        
    ]
}

Response status: 201 CREATED
Response headers: Location: http://185.12.95.60:8081/ruber/markets/13/orders/11
Exceptions: NO_SUCH_MARKET

3.2 Get order by id

Request: GET /markets/{market_id}/orders/{id}
Request headers: Accept=application/json
Response:

{
    !"id": INTEGER,
    !"title": STRING,
    "description": STRING,
    !"status": ENUM("WAITING", "PAID", "DONE", "CANCELLED"),
    !"created_timestamp": LONG,
    !"deadline_timestamp": LONG or NULL,
    !"customer": {
        !"name": STRING,
        !"phone": STRING,
        !"vk_id": INTEGER or NULL
    },
    !"shipment": NULL or {
        !"address": STRING,
        !"cost": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99"
    },
    !"discount": NULL or {
        !"title": STRING,
        !"description": STRING,
        !"thumb_photo": URL e.g. "http://google.com/pic1",
        !"cost": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99"
    },
    !"item_replicas": [
        {
            !"id": INTEGER,
            !"title": STRING,
            !"description": STRING,
            !"thumb_photo": URL e.g. "http://google.com/pic1",
            !"price": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99",
            !"amount": INTEGER    
        },
        {
            !"id": INTEGER,
            !"title": STRING,
            !"description": STRING,
            !"thumb_photo": URL e.g. "http://google.com/pic1",
            !"price": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99",
            !"amount": INTEGER,
            !"vk_id": INTEGER    
        }
        ...        
    ]
}

Note method returns item_replicas and vk_item_replicas in item_replicas array
Exceptions: NO_SUCH_ORDER, NO_SUCH_MARKET

3.3 Get orders

Request: GET /markets/{market_id}/orders
Request headers: Accept=application/json
Response:

[
    {
        !"id": INTEGER,
        !"title": STRING,
        !"description": STRING,
        !"status":  ENUM("WAITING", "PAID", "DONE", "CANCELLED"),
        !"order_positions": INTEGER,
        !"pinned_items": INTEGER
    },
    ...
]

Exceptions: NO_SUCH_MARKET

3.4 Edit order

Request: PUT /markets/{market_id}/orders/{id}
Request headers: Content-Type=application/json
Request body:

{
    "title": STRING,
    "description": STRING,
    "status": ENUM("WAITING", "PAID", "DONE", "CANCELLED"),
    "deadline_timestamp": LONG or NULL,
    "discount": NULL or {
        "title": STRING,
        "description": STRING,
        "thumb_photo": URL e.g. "http://google.com/pic1",
        "cost": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99"
    },
    "shipment": NULL or {
        "address": STRING,
        "cost": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99"
    },
    "customer": {
        "name": STRING,
        "phone": STRING,
        "vk_id": INTEGER or NULL
    }
}

Response body:

{
    !"id": INTEGER,
    !"title": STRING,
    "description": STRING,
    !"status": ENUM("WAITING", "PAID", "DONE", "CANCELLED"),
    !"created_timestamp": LONG,
    !"deadline_timestamp": LONG or NULL,
    !"customer": {
        !"name": STRING,
        !"phone": STRING,
        !"vk_id": INTEGER or NULL
    },
    !"shipment": NULL or {
        !"address": STRING,
        !"cost": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99"
    },
    !"discount": NULL or {
        !"title": STRING,
        !"description": STRING,
        !"thumb_photo": URL e.g. "http://google.com/pic1",
        !"cost": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99"
    },
    !"item_replicas": [
        {
            !"id": INTEGER,
            !"title": STRING,
            !"description": STRING,
            !"thumb_photo": URL e.g. "http://google.com/pic1",
            !"price": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99",
            !"amount": INTEGER    
        },
        {
            !"id": INTEGER,
            !"title": STRING,
            !"description": STRING,
            !"thumb_photo": URL e.g. "http://google.com/pic1",
            !"price": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99",
            !"amount": INTEGER,
            !"vk_id": INTEGER    
        }
        ...        
    ]
}

Response status: 200 OK
Exceptions: INVALID_REQUEST_JSON, NO_SUCH_ORDER, NO_SUCH_MARKET, NOT_ENOUGH_ARGUMENTS if you try to create(not update) discount or shipment or deadline_timestamp but not specified some fields.

4 Item replicas

4.1 Get item replica by id

Request: GET /markets/{market_id}/orders/{order_id}/item_replicas/{replica_id}
Request headers: Accept=application/json
Response body:

{
    !"id": INTEGER,
    !"title": STRING,
    !"description": STRING,
    !"thumb_photo": URL e.g. "http://google.com/pic1",
    !"price": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99",
    !"amount": INTEGER,
    
    !"vk_id": INTEGER (specified for vk_item_replica only)
}

Exceptions: NO_SUCH_ORDER, NO_SUCH_MARKET, NO_SUCH_ORDER_POSITION

4.2 Get item replicas

Request: GET /markets/{market_id}/orders/{order_id}/item_replicas
Request headers: Accept=application/json
Response body:

[
    {
        !"id": INTEGER,
        !"title": STRING,
        !"description": STRING,
        !"thumb_photo": URL e.g. "http://google.com/pic1",
        !"price": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99",
        !"amount": INTEGER,
        
        !"vk_id": INTEGER (specified for vk_item_replica only)
    },
    ...
]

Exceptions: NO_SUCH_ORDER, NO_SUCH_MARKET

4.3 Delete item replica

Request: DELETE /markets/{market_id}/orders/{order_id}/item_replicas/{replica_id}
Response status: 204 NO CONTENT
Exceptions: NO_SUCH_ORDER, NO_SUCH_ORDER_POSITION, NO_SUCH_MARKET

4.4 Add item replica

Request: POST /markets/{market_id}/orders/{order_id}/item_replicas
Request headers: Content-Type=application/json
Request body:

{
    !"title": STRING,
    !"description": STRING,
    !"thumb_photo": URL e.g. "http://google.com/pic1",
    !"price": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99",
    !"amount": INTEGER,
    
    !"vk_id": INTEGER (specify for vk_item_replica only)
}

Response body:

{
    !"id": INTEGER,
    !"title": STRING,
    !"description": STRING,
    !"thumb_photo": URL e.g. "http://google.com/pic1",
    !"price": POSITIVE BIGDECIMAL(scale = 2) e.g. "14.99",
    !"amount": INTEGER,
    
    !"vk_id": INTEGER (specified for vk_item_replica only)
}

Response status: 201 CREATED
Response headers: Location: http://185.12.95.60:8081/ruber/markets/13/orders/11/item_replicas/14
Exceptions: NO_SUCH_ORDER, NO_SUCH_MARKET

5 Pinned messages for Order

5.1 Get pinned message by id

Request: GET /markets/{market_id}/orders/{order_id}/pinned_messages/{message_id}
Request headers: Accept=application/json
Response body:

{
    !"id": INTEGER,
    !"position": INTEGER,
    !"vk_message_id": LONG,
    !"created_timestamp": LONG
}

Exceptions: NO_SUCH_ORDER, NO_SUCH_PINNED_ITEM, NO_SUCH_MARKET

5.2 Get pinned messages

Request: GET /markets/{market_id}/orders/{order_id}/pinned_messages
Request headers: Accept=application/json
Response body:

[
    {
        !"id": INTEGER,
        !"position": INTEGER,
        !"vk_message_id": LONG,
        !"created_timestamp": LONG
    },
    ...
]

Exceptions: NO_SUCH_ORDER, NO_SUCH_MARKET

5.3 Delete pinned message

Request: DELETE /markets/{market_id}/orders/{order_id}/pinned_messages/{message_id}
Response status: 204 NO CONTENT
Exceptions: NO_SUCH_ORDER, NO_SUCH_PINNED_ITEM, NO_SUCH_MARKET

5.4 Add pinned message

Request: POST /markets/{market_id}/orders/{order_id}/pinned_messages
Request headers: Content-Type=application/json
Request body:

{
    !"position": INTEGER,
    !"vk_message_id": LONG
}

Response body:

{
    !"id": INTEGER,
    !"position": INTEGER,
    !"vk_message_id": LONG,
    !"created_timestamp": LONG
}

Response status: 201 CREATED
Response headers: Location: http://185.12.95.60:8081/ruber/markets/13/orders/11/pinned_messages/14
Exceptions: NO_SUCH_ORDER, NO_SUCH_MARKET

6 Pinned texts for Order

6.1 Get pinned text by id

Request: GET /markets/{market_id}/orders/{order_id}/pinned_texts/{text_id}
Request headers: Accept=application/json
Response body:

{
    !"id": INTEGER,
    !"position": INTEGER,
    !"text": STRING,
    !"created_timestamp": LONG
}

Exceptions: NO_SUCH_ORDER, NO_SUCH_PINNED_ITEM, NO_SUCH_MARKET

6.2 Get pinned texts

Request: GET /markets/{market_id}/orders/{order_id}/pinned_texts
Request headers: Accept=application/json
Response body:

[
    {
        !"id": INTEGER,
        !"position": INTEGER,
        !"text": STRING,
        !"created_timestamp": LONG
    },
    ...
]

Exceptions: NO_SUCH_ORDER, NO_SUCH_MARKET

6.3 Delete pinned text

Request: DELETE /markets/{market_id}/orders/{order_id}/pinned_texts/{text_id}
Response status: 204 NO CONTENT
Exceptions: NO_SUCH_ORDER, NO_SUCH_PINNED_ITEM, NO_SUCH_MARKET

6.4 Add pinned text

Request: POST /markets/{market_id}/orders/{order_id}/pinned_texts
Request headers: Content-Type=application/json
Request body:

{
    !"position": INTEGER,
    !"text": STRING
}

Response body:

{
    !"id": INTEGER,
    !"position": INTEGER,
    !"text": STRING,
    !"created_timestamp": LONG
}

Response status: 201 CREATED
Response headers: Location: http://185.12.95.60:8081/ruber/markets/13/orders/11/pinned_texts/14
Exceptions: NO_SUCH_ORDER, NO_SUCH_MARKET

7 Pinned files for Order

7.1 Get pinned file by id

Request: GET /markets/{market_id}/orders/{order_id}/pinned_files/{file_id}
Request headers: Accept=application/json
Response body:

{
    !"id": INTEGER,
    !"position": INTEGER,
    !"file_name": STRING,
    !"created_timestamp": LONG
}

Exceptions: NO_SUCH_ORDER, NO_SUCH_PINNED_ITEM, NO_SUCH_MARKET

7.2 Get pinned files

Request: GET /markets/{market_id}/orders/{order_id}/pinned_files
Request headers: Accept=application/json
Response body:

[
    {
        !"id": INTEGER,
        !"position": INTEGER,
        !"file_name": STRING,
        !"created_timestamp": LONG
    },
    ...
]

Exceptions: NO_SUCH_ORDER, NO_SUCH_MARKET

7.3 Download pinned file content by id

Request: GET /markets/{market_id}/orders/{order_id}/pinned_files/{file_id}/content
Request headers: Accept=application/octet-stream
Exceptions: NO_SUCH_ORDER, NO_SUCH_PINNED_ITEM, NO_SUCH_MARKET

7.4 Delete pinned file

Request: DELETE /markets/{market_id}/orders/{order_id}/pinned_files/{file_id}
Response status: 204 NO CONTENT
Exceptions: NO_SUCH_ORDER, NO_SUCH_PINNED_ITEM, NO_SUCH_MARKET

7.5 Add pinned file

NOTE! This is a multipart request. You must follow the appropriate standart
Request: POST /markets/{market_id}/orders/{order_id}/pinned_files/{file_id}
Request headers: Accept=application/json, Content-Type=multipart/form-data; boundary={boundary}
Request body: link
Request notes: do not forget about the boundary in Content-Type=multipart/form-data header. You must set the position parameter for this pinned file in requeset body. See the request body link.
Response body:

{
    !"id": INTEGER,
    !"position": INTEGER,
    !"file_name": STRING,
    !"created_timestamp": LONG
}

Response status: 201 CREATED
Response headers: Location: http://185.12.95.60:8081/ruber/markets/13/orders/12/pinned_files/43
Exceptions: NO_SUCH_ORDER, MULTIPART_IO_EXCEPTION, NO_SUCH_MARKET

8 Connected Vk markets

8.1 Get connected vk markets

Request: GET /markets
Request headers: Accept=application/json
Response body:

[
    INTEGER,
    INTEGER,
    INTEGER,
    ...
]
8.2 Add connected vk market

Request: POST /markets
Request headers: Content-Type=application/json
Request body:

{
    !"vk_group_id": INTEGER
}

Response body:

[
    INTEGER,
    INTEGER,
    INTEGER,
    ...
]

Response status: 201 CREATED
Exceptions: INVALID_REQUEST_JSON if vk_group_id is missed or null

8.3 Delete connected vk market

Request: DELETE /markets/{vk_group_id}
Response status: 204 NO CONTENT

Clone this wiki locally