Ajax API规范

api

---

Result filtering, sorting & searching

Filtering: /tickets?state=open
Sorting: /tickets?sort=-priority,created_at
Searching: /tickets?q=return
Aliases for common queries: /tickets/recently_closed

Http Header

Request
- Content-Type: application/json
- Content-Type: application/x-www-form-urlencoded
Response
- Content-Type: application/json

List Resources

URI:
GET /resources
Parameters
- state: 状态或类型，如open
- sort_by: 排序字段名称，如updated_at
- order: 排序方向，升序（aesc）或降序（desc）
- per_page: 分页大小
- page: 页数，从1开始

Status Code

200 ok - 成功返回状态，对应，GET,PUT,PATCH,DELETE.
201 created - 成功创建。
304 not modified - HTTP缓存有效。
400 bad request - 请求格式错误。
401 unauthorized - 未授权。
403 forbidden - 鉴权成功，但是该用户没有权限。
404 not found - 请求的资源不存在
405 method not allowed - 该http方法不被允许。
410 gone - 这个url对应的资源现在不可用。
415 unsupported media type - 请求类型错误。
422 unprocessable entity - 校验错误时用。
429 too many request - 请求过多。

FAQ

JSONP


callback_function({
status_code: 200,
next_page: "https://..",
response: {
... actual JSON response body ...
}
})


Versioning

https://www.googleapis.com/language/translate/v2?key=INSERT-YOUR-KEY
HEADER: facebook-api-version:v2.0
https://api.twitter.com/1.1/account/settings.json

snake_case vs camelCase for field names

Food for thought: I've always felt that snake_case is easier to read than JavaScript's convention of camelCase. I just didn't have any evidence to back up my gut feelings, until now. Based on an eye tracking study on camelCase and snake_case (PDF) from 2010, snake_case is 20% easier to read than camelCase! That impact on readability would affect API explorability and examples in documentation.

Pretty print by default & ensure gzip is supported

Don't use an envelope by default, but make it possible when needed

Auto loading related resource representations

/tickets/12?embed=customer.name,assigned_user


{
"id" : 12,
"subject" : "I have a question!",
"summary" : "Hi, ....",
"customer" : {
"name" : "Bob"
},
assigned_user: {
"id" : 42,
"name" : "Jim",
}
}


Rate limiting

X-Rate-Limit-Limit - The number of allowed requests in the current period
X-Rate-Limit-Remaining - The number of remaining requests in the current period
X-Rate-Limit-Reset - The number of seconds left in the current period

Error


{
"code" : 1234,
"message" : "Something bad happened <img src="http://blog.jobbole.com/wp-includes/images/smilies/icon_sad.gif" alt=":-(" class="wp-smiley"> ",
"description" : "More details about the error here"
}