-
Notifications
You must be signed in to change notification settings - Fork 0
Home
#API Version 1 Design This document is an overview of the first iteration of the rate API and associated infrastructure, to support third party company with rate-limiting and security.
#URL Convention The external API is accessed with the following URL layout:
http://rate.kagogo.co/versionid/entity/action
VersionID is v1. Results of all commands are returned in JSON format.
#Authentication
Authentication tokens are sent as part of the HTTP request header. Below is a sample API request URL and an example of the authentication headers:
Request URL: http://rate.kagogo.co/v1/rate/get?object_id=98AksD4
API: e2589f9bacdf1cab556843c00bf0a6222ab24c64
Timestamp: 1370892622
Signature: fUWDCJump/cOsWjE+kI0AueIhZA=
##API Key
Your API key is a unique key used to identify your application when making requests to the Rate API.
All API requests require an API key to be passed as part of the HTTP header.
To obtain an API key please register here.
Example:
API: e2589f9bacdf1cab556843c00bf0a6222ab24c64
##API Secret
An API Secret will be sent to you via Email or Developer API website once the application has been approved. You should not share your API key with anyone or make it public, as it is used for secure signature generation.
Example:
0ca06fef862c36bb4d93f5122ac49f0509e67778
##Timestamp
The time of the API request, in UNIX timestamp format.
Example:
Timestamp: 1370892622
##Signature
Signing a request involves calculating a token and including it with the request, in order to authenticate API calls.
A signature is generated by using various parts of the HTTP request to create a base string and then performing a one-way encryption on the base string.
###Step 1 — Build parameter string
Gather all GET and POST parameters of the request, as well as the API Key and Timestamp header values (using the keys "auth_api" and "auth_timestamp" respectively). This combined list of parameters will be encoded into a single string by following these steps:
- URL-encode every parameter value
- Sort the list of parameters alphabetically by key
- For each key/value pair:
- Append the key
- Append a '=' symbol
- Append the encoded value
- If there are additional parameters, append a '&' symbol
Example parameter string:
auth_api=e2589f9bacdf1cab556843c00bf0a6222ab24c64&auth_timestamp=1370892622&object_id=98AksD4
###Step 2 — Build signature base string
Generate the signature base string by following these steps:
- Convert the request method to uppercase
- Append an '&' character
- Append the full request URL, including protocol and minus any query string, URL-encoded
- Append an '&' character
- Append the parameter string from Step 1, URL-encoded
Example signature base:
GET&https%3A%2F%2Frate.kagogo.co%2Fv%2F1%2Frate%2Fget&auth_api%3Dd83a2db49dc70ebd2499c103f867a95254772aa0%26auth_timestamp%3D1370892622%26object_id%3D98AksD4
###Step 3 — Generate a signing token
Generate a signing token by following these steps:
- Append the API Key to an empty string
- Append a '&' character
- Append the value of the Timestamp header
- Append a '&' character
- Append your API Secret
Example signing token:
e2589f9bacdf1cab556843c00bf0a6222ab24c64&1370892622&0ca06fef862c36bb4d93f5122ac49f0509e67778
###Step 4 — Calculate the signature
The signature calculating uses the HMAC-SHA1 algorithm. Calculate the signature by passing the signature base to the HMAC-SHA1 algorithm as the message and the signing token as the hashing key. The result of this algorithm is a binary string, which must be Base64 encoded and passed as the Signature header.
Example signature:
Signature: fUWDCJump/cOsWjE+kI0AueIhZA=
#Error Codes
2000 Ok
2100 Entity Created On Server
4000 Bad Request
4001 API Key Is Missing
4002 Device Key Is Missing
4003 API Not Registered
4004 Device Not Registered
4005 Missing Signature
4006 Signature Is Invalid
4007 Some Or All Device Information Missing
4016 The Search Term is Empty
4020 Some Or All Request Parameters Missing
4034 Cannot post duplicate comment
4100 Unauthorized Request
4101 API Key Provided Is Unauthorized To Access This Method
4102 Device Key Is Unauthorized To Access This Method
4300 Forbidden Request
4301 API Key Is Currently Blocked
4302 Device Key Is Currently Blocked
4400 Not Found
4401 Requested API Method Not Found
4404 Device Type Not Found
4500 Request Method Used Is Not Allowed (usually when POST used instead of GET or vice-versa)
4501 Requested API Method Supports HTTPS Only
5000 Internal Server Error
6000 App Version No Longer Supported. Please Upgrade.
#Rate Limiting In order to avoid abuse of the API system, limits are placed on the number of accesses per hour, by Device Key, then by API Key. This limit varies by call but is automatically enforced by the system.
The API Key limit is a percentage based on the number of Device Keys assigned to that API Key reaching their limit per hour. For example, if the limit is 50%, and an API Key has 10 assigned Devices, and 5 of those devices reach the Device limit, that disables the entire API Key for one hour. The percentage is to be determined.
When a Device or API reaches its limit, all subsequent calls will return an error code for one hour, until the reset time is reached.
Headers Every API call returns the following headers:
- Limit: The hard per hour limit for that API call.
- Remaining: The number of API calls left for that Device Key for this hour.
- Timeout: The timestamp of when service will resume, returned in standard HTTP date format (Tue, 15 Nov 1994 08:12:31 GMT). Zero if Remaining is non-zero. Remaining is set by a Device Key's first call to the API and deducted for each subsequent call from that point to an hour forward, at which point it is reset to the set limit.
If Remaining reaches zero, it increases the API Key rate limit count. If that number reaches a to-be-determined number, the entire API Key is disabled for one hour.
Limit is zero on non-limited calls, and Remaining is set to the system-wide limit.
This information will allow third-party developers to manage their apps appropriately.
#Objects Common objects returned from the API. Embedded objects are referenced using "" notation.
Status
"status": {
"code": 2000,
"message": "Ok",
"details": "A user friendly status message."
}
Object Every entity is marked as Object which includes(user, company, service, product and etc)
"object": {
"id": "5397c4ff64e040000064db09",
"name": "nexus 5",
"object_id": "1234567890",
"rate": 0,
"provider": "53855ce554f713eb2829c9dd",
"feedback": {
"good": 0,
"normal": 0,
"bad": 0
},
"score": 0.5,
"popularity": 1,
"create_at": 1402455295308,
"categories": {
"item_as_described": {
"rate": 0,
"count": 0
},
"communication": {
"rate": 0,
"count": 0
},
"shipping_time": {
"rate": 0,
"count": 0
},
"shipping_charges": {
"rate": 5,
"count": 1
}
}
}
Rate
"rate": {
"id": 32456y7u8i,
}
Feedback
"feedback": {
"id": "53981d77f5c77e000078d7a6",
"object_id": "1234567890",
"user": "sasdfssa",
"feedback": "bad test1",
"create_at": 1402477943790,
"grade": "bad"
}
#Global Parameters delay_response Value: Non-empty (i.e. "1", "true")
Intentionally delays the response sent back from the API. The length of the delay is controlled within the API and cannot be modified by the client.
#Command Reference
Request method: POST
Authentication Level: API
Rate Limit: None
Save a rate
-
object_id the object id from third party
-
name the name of the object
-
provider the provider of id (local, facebook, twitter and etc)
-
user_id the user id from third party who rates this object
-
rate The score of the rate (0 ~ 5)
-
type The type of this object e.g. book, agent, lawyer, mobile and etc. (option)
-
category The category of this rate (required, if app is defined with categories)
status object
http://rate.kagogo.co/v1/rate/save
#!json
{
"status":{
"code":2000,
"message":"OK"
},
"object":{
"id":"5397c4ff64e040000064db09",
"name":"Enda Xue",
"object_id":"1234567890",
"rate":0,
"provider":"53855ce554f713eb2829c9dd",
"feedback":{
"good":3,
"normal":2,
"bad":2
},
"score":10.5,
"popularity":21,
"create_at":1402455295308,
"categories":{
"item_as_described":{
"rate":3,
"count":4
},
"communication":{
"rate":4,
"count":2
},
"shipping_time":{
"rate":3,
"count":3
},
"shipping_charges":{
"rate":5,
"count":1
}
}
}
}
Request method: GET
Authentication Level: API
Rate Limit: None
Get rate of the Object
- object_id the object id from third party
status object
http://rate.kagogo.co/v1/rate/get?object_id=1234567890
#!json
{
"status":{
"code":2000,
"message":"OK"
},
"object":<object>
}
Request method: POST
Authentication Level: API
Rate Limit: None
Save a feedback
-
object_id the object id from third party
-
name the name of the object
-
provider the provider of id (local, facebook, twitter and etc)
-
user_id the user id from third party who rates this object
-
type the type of this object e.g. book, agent, lawyer, mobile and etc. (option)
-
feedback feedback of a user from the App
-
grade ['good','normal','bad'] the grade of the feedback
status object
http://rate.kagogo.co/v1/feedback/save
#!json
{
"status":{
"code":2000,
"message":"OK"
},
"object":<object>
}
Request method: GET
Authentication Level: API
Rate Limit: None
Get feedbacks of the Object
-
object_id the object id from third party
-
grade the grade of the feedbacks ["good","normal","bad"] (options)
-
since_id pagination id to get previous feedbacks (options)
-
max_id pagination id to get next feedbacks (options)
-
number the number of returns (options)
status feedbacks
http://rate.kagogo.co/v1/feedback/get?object_id=1234567890
#!json
{
"status": {
"code": 2000,
"message": "OK"
},
"feedbacks": [<feedback>,<feedback>,<feedback>]
}
Request method: GET
Authentication Level: API
Rate Limit: None
List objects by type("mobile","agent") of the App. e.g. Get mobile phones / Real estate agent by rating score
-
type the type of objects (the type in rate/save or feedback/save api call) e.g. TV, agent
-
sort_by the field of the sorting list ["score","popularity","latest"], "score" by default (options)
-
since_id pagination id, score or popularity to get previous load of objects. (options)
-
max_id pagination id, score or popularity to get next load of objects (options)
-
number the number of returns (options)
note: the relationship between sort_by and since_id/max_id should follow this: ["score" => score, "popularity"=>popular,"latest"=>id]
status feedbacks
http://rate.kagogo.co/v1/feedback/get?object_id=1234567890
#!json
{
"status": {
"code": 2000,
"message": "OK"
},
"objects": [<object>,<object>,<object>]
}