Restful Actions
1. Introduction
As shown in Create Request , you can use your preferred tools to monitor Restful Actions between our web application with the server.
Chrome | Safari | Firefox |
|---|---|---|
 Chrome | Safari | |
Most of the API End Points are accessible via GET/PUT/POST/DELETE actions. All you need to do is to simulate the actions in your application.
Please be aware to ease the difference between browsers, we treat PUT and POST actions as the same.
We use 'id' field in requests to distinguish Add and Update action. One action is treated as Update if there's valid 'id' value (exist and not NULL), otherwise it would be treated as Add action.
2. Examples
for example: consignments
Add
URI | |
Method | POST |
Content-Type | application/json |
URL Param | - |
Body Param | {
"delivery_service_id":1471,
"contact":"Eddie dawson",
"address_line1":"37 LYNAS gardens",
"address_line2":"Grassendale",
"city":"liverpool",
"county":"Merseyside",
"post_code":"l199bl",
"country_iso":"GB",
"telephone":"Tel:01519033363",
"email":null,
"sales_reference":"3",
"type":"LOCAL"
} |
Response | {
"data":[
{
"commodity_code":null,
"total_price_customs_export":null,
"name_customs":null,
"total_quantity":null,
"weight":null,
"price":null,
"price_customs_export":null,
"period":null,
"type":"LOCAL",
"total":null,
"external_code":null,
"external_code1":null,
"external_code2":null,
"max_length":null,
"max_width":null,
"max_depth":null,
"handling_fee_first_item":null,
"handling_fee_other_item":null,
"handling_fee_first_product":null,
"handling_fee_other_product":null,
"handling_fee":null,
"handling_fee_urgent_consignment":null,
"handling_fee_limit":null,
"delivery_fee":null,
"delivery_fee_type":null,
"return_consignment_id":null,
"return_consignment_action_type":null,
"return_consignment_action_name":null,
"quantity":null,
"battery_type_name_list":null,
"delivery_service_name":"飞鸟小包",
"sku_count":null,
"product_company_ref":null,
"id":1707170020000004,
"company_id":2,
"client_id":1,
"warehouse_id":null,
"consignment_product_quantity":1,
"consignment_product_reference":"1",
"delivery_service_id":1471,
"delivery_service_id_internal":1471,
"delivery_package_size_id":432,
"total_price":"0.00",
"total_delivery_fee":"999.00",
"total_handling_fee":"0.00",
"total_weight":"30.00",
"total_volume":"504000.00",
"total_volume_weight":"504000.0000",
"guarantee_percentage":"0.00",
"contact":"Eddie dawson",
"business_name":null,
"address_line1":"37 LYNAS gardens",
"address_line2":"Grassendale",
"address_line3":null,
"city":"liverpool",
"county":"Merseyside",
"post_code":"l199bl",
"country_iso":"GB",
"telephone":"Tel:01519033363",
"email":null,
"sender_contact":null,
"sender_business_name":null,
"sender_address_line1":null,
"sender_address_line2":null,
"sender_address_line3":null,
"sender_city":null,
"sender_county":null,
"sender_post_code":null,
"sender_country_iso":null,
"sender_email":null,
"sender_telephone":null,
"sales_reference":"3",
"payment_reference":null,
"delivery_reference":null,
"tracking_reference":null,
"special_instruction":null,
"neighbour_instruction":null,
"temp_consignment_info_id":3,
"is_urgent":0,
"is_forced_delivery_service":0,
"create_time":"2017-07-18 01:04:34",
"finish_time":"2017-06-21 08:00:00",
"arrive_time":null,
"update_time":"2017-06-30 08:00:00",
"status":"FINISHED",
"primary_keys":[
"id"
],
"delivery_service_special_type":"HKSP",
"delivery_service_is_use_delivery_agent_account_address":1,
"consignment_delivery_agent-net17track_code":"ZZ",
"country_name":"UNITED KINGDOM"
}
],
"success":true,
"moduleName":"client"
} |
Query Single Record Detail
URI | |
Method | GET |
Content-Type | application/json |
URL Param | id=1707170020000004 |
Body Param | - |
Response | {
"total":1,
"data":[
{
"commodity_code":null,
"total_price_customs_export":null,
"name_customs":null,
"total_quantity":null,
"weight":null,
"price":null,
"price_customs_export":null,
"period":null,
"type":"LOCAL",
"total":null,
"external_code":null,
"external_code1":null,
"external_code2":null,
"max_length":null,
"max_width":null,
"max_depth":null,
"handling_fee_first_item":null,
"handling_fee_other_item":null,
"handling_fee_first_product":null,
"handling_fee_other_product":null,
"handling_fee":null,
"handling_fee_urgent_consignment":null,
"handling_fee_limit":null,
"delivery_fee":null,
"delivery_fee_type":null,
"return_consignment_id":null,
"return_consignment_action_type":null,
"return_consignment_action_name":null,
"quantity":null,
"battery_type_name_list":null,
"delivery_service_name":"飞鸟小包",
"sku_count":null,
"product_company_ref":null,
"id":1707170020000004,
"company_id":2,
"client_id":1,
"warehouse_id":null,
"consignment_product_quantity":1,
"consignment_product_reference":"1",
"delivery_service_id":1471,
"delivery_service_id_internal":1471,
"delivery_package_size_id":432,
"total_price":"0.00",
"total_delivery_fee":"999.00",
"total_handling_fee":"0.00",
"total_weight":"30.00",
"total_volume":"504000.00",
"total_volume_weight":"504000.0000",
"guarantee_percentage":"0.00",
"contact":"Eddie dawson",
"business_name":null,
"address_line1":"37 LYNAS gardens",
"address_line2":"Grassendale",
"address_line3":null,
"city":"liverpool",
"county":"Merseyside",
"post_code":"l199bl",
"country_iso":"GB",
"telephone":"Tel:01519033363",
"email":null,
"sender_contact":null,
"sender_business_name":null,
"sender_address_line1":null,
"sender_address_line2":null,
"sender_address_line3":null,
"sender_city":null,
"sender_county":null,
"sender_post_code":null,
"sender_country_iso":null,
"sender_email":null,
"sender_telephone":null,
"sales_reference":"3",
"payment_reference":null,
"delivery_reference":null,
"tracking_reference":null,
"special_instruction":null,
"neighbour_instruction":null,
"temp_consignment_info_id":3,
"is_urgent":0,
"is_forced_delivery_service":0,
"create_time":"2017-07-18 01:04:34",
"finish_time":"2017-06-21 08:00:00",
"arrive_time":null,
"update_time":"2017-06-30 08:00:00",
"status":"FINISHED",
"primary_keys":[
"id"
],
"delivery_service_special_type":"HKSP",
"delivery_service_is_use_delivery_agent_account_address":1,
"consignment_delivery_agent-net17track_code":"ZZ",
"country_name":"UNITED KINGDOM"
}
],
"success":true,
"moduleName":"client"
} |
Query Records List
URI | |
Method | GET |
Content-Type | application/json |
URL Param | start=0&limit=50&sort=[{"property":"update_time","direction":"DESC"}] |
| start: the return record list start offset, , Optional Default 0 |
Body Param | - |
Response | {
"total":914567,
"data":Array[50],
"success":true,
"currency":"CNY",
"moduleName":"admin"
} |
The common query params when query record list
When we query record list, we have another common query params besides the param "start", "limit", "sort"，seeing below (the following params should send to server by GET request)
param | type | note | examples |
selectFields | string | the columns which should be return when query record list (this value should be URL encoded) | such as we need to return fields : status,is_urgent,total_weight,total_volume_weight,type,update_time,create_time. we should concat these field names with comma, then do URL encoded finally, the url params should be: selectFields=status%2Cis_urgent%2Ctotal_weight%2Ctotal_volume_weight%2Ctype%2Cupdate_time%2Ccreate_time
|
filter | string | the filter condition which should be applied when query record list (this value should be URL encoded) | such as we need to query the consignment list which status is FINISHED ,and last update time is newer than 2017-09-10，条the query conditions should be : [ {"type":"date","comparison":"gt","value":"2017-09-10","field":"update_time"}, {"type":"list","value":["FINISHED"],"field":"status"} ]. after url encoded，the url params should be: filter=5B%7B%22type%22%3A%22date%22%2C%22comparison%22%3A%22gt%22%2C%22value%22%3A%222017-09-10%22%2C%22field%22%3A%22update_time%22%7D%2C%7B%22type%22%3A%22list%22%2C%22value%22%3A %5B%22FINISHED%22%5D%2C%22field%22%3A%22status%22%7D%5D |
custom defined filter field by each table list | string |
In order to fullfill the different requirements, some API can use query filter on some frequently used fields. we can directly send params "fieldname=fieldvalue" to these API. Please refer to the relevant API documentation for the conditions available for each API | such as Product list，frequently query by client_ref or status，so we support this two fileds used as custom filter。 then we can use this fields as url params: client_ref=IPxxx or status=PENDING (you can use multi conditions in same time) |
Modify
URI | |
Method | POST |
Content-Type | application/json |
URL Param | id=1707170020000004 |
Body Param | {
"delivery_service_id":1471,
"contact":"Eddie dawson",
"address_line1":"37 LYNAS gardens",
"address_line2":"Grassendale",
"city":"liverpool",
"county":"Merseyside",
"post_code":"l199bl",
"country_iso":"GB",
"telephone":"Tel:01519033363",
"email":null,
"sales_reference":"3",
"type":"LOCAL"
} |
Response | {
"data":[
{
"commodity_code":null,
"total_price_customs_export":null,
"name_customs":null,
"total_quantity":null,
"weight":null,
"price":null,
"price_customs_export":null,
"period":null,
"type":"LOCAL",
"total":null,
"external_code":null,
"external_code1":null,
"external_code2":null,
"max_length":null,
"max_width":null,
"max_depth":null,
"handling_fee_first_item":null,
"handling_fee_other_item":null,
"handling_fee_first_product":null,
"handling_fee_other_product":null,
"handling_fee":null,
"handling_fee_urgent_consignment":null,
"handling_fee_limit":null,
"delivery_fee":null,
"delivery_fee_type":null,
"return_consignment_id":null,
"return_consignment_action_type":null,
"return_consignment_action_name":null,
"quantity":null,
"battery_type_name_list":null,
"delivery_service_name":"飞鸟小包",
"sku_count":null,
"product_company_ref":null,
"id":1707170020000004,
"company_id":2,
"client_id":1,
"warehouse_id":null,
"consignment_product_quantity":1,
"consignment_product_reference":"1",
"delivery_service_id":1471,
"delivery_service_id_internal":1471,
"delivery_package_size_id":432,
"total_price":"0.00",
"total_delivery_fee":"999.00",
"total_handling_fee":"0.00",
"total_weight":"30.00",
"total_volume":"504000.00",
"total_volume_weight":"504000.0000",
"guarantee_percentage":"0.00",
"contact":"Eddie dawson",
"business_name":null,
"address_line1":"37 LYNAS gardens",
"address_line2":"Grassendale",
"address_line3":null,
"city":"liverpool",
"county":"Merseyside",
"post_code":"l199bl",
"country_iso":"GB",
"telephone":"Tel:01519033363",
"email":null,
"sender_contact":null,
"sender_business_name":null,
"sender_address_line1":null,
"sender_address_line2":null,
"sender_address_line3":null,
"sender_city":null,
"sender_county":null,
"sender_post_code":null,
"sender_country_iso":null,
"sender_email":null,
"sender_telephone":null,
"sales_reference":"3",
"payment_reference":null,
"delivery_reference":null,
"tracking_reference":null,
"special_instruction":null,
"neighbour_instruction":null,
"temp_consignment_info_id":3,
"is_urgent":0,
"is_forced_delivery_service":0,
"create_time":"2017-07-18 01:04:34",
"finish_time":"2017-06-21 08:00:00",
"arrive_time":null,
"update_time":"2017-06-30 08:00:00",
"status":"FINISHED",
"primary_keys":[
"id"
],
"delivery_service_special_type":"HKSP",
"delivery_service_is_use_delivery_agent_account_address":1,
"consignment_delivery_agent-net17track_code":"ZZ",
"country_name":"UNITED KINGDOM"
}
],
"success":true,
"moduleName":"client"
} |
Delete
URI | |
Method | DELETE |
Content-Type | application/json |
URL Param | id=1707170020000004 |
Body Param | - |
Response | {
"success":true,
"message":"Delete Successfully",
"refresh":false,
"moduleName":"client"
} |
3. More
all table list in birdsystem can action with Restful.