使用连接符来连接多个单词
为什么是连字符(-)而不是下划线等呢?因为 URI 的主机名(域名)允许使用连字符而禁止使用下划线,且不区分大小写。其次点字符具有特殊含义。
其实最好的方法是尽量避免在 URI 中使用多个单词。比如,不用 popular_users,而用 users/popular,或者用查询字符串的方式。
分页的设计是否恰当
① 获取数据量和获取位置的查询参数: 通过 per_page=50&page=3 或 limit=50&offset=100 组合。page 一般从1开始计数,offet 则从 0 开始计数。但这种使用相对位置的方法存在以下几个问题:(1) 性能问题(为了获取第2302条开始的数据,也需要从首条数据开发计数) (2) 如果数据更新的频率很高,会导致当前获取的数据出现一定的偏差(如数据重复)。
② 使用绝对位置来获取数据。如“某个 ID 之前”或“某个日期之前”等条件。
另外,对于“详细的错误代码”是指 API 提供者针对各个错误自定义的代码。这些代码的清单应该和 API 一起以联机文档的方式提供。对于这个代码,建议和 HTTP 状态码一样,如用4位数表示,1字头表示通用错误,2字头表示用户信息错误等。
另外,有时会在错误的提示信息里同时包含面向非开发人员的信息和面向开发人员的信息。
Web API Checklist
每个点的详细说明
URI 是否短小且容易输入 在表示的信息量相同的情况下,使用短小、简单的表述方式更易于理解和记忆,并能减少输入时的错误。
案例
URI 是否能让人一眼看懂 即使没有其他提示,也能理解其用途。
没有大小写混用的 URI
修改方便的 URI
案例
URI 是否反映了服务器端的架构
规则统一的 URI 指 URI 所用的词汇和结构等。
案例:①查询字符串与URI路径 ②单复数
有没有使用合适的 HTTP 方法
GET
表示获取信息。一般不会修改服务器上的已有资源(当然,已读/未读、最后访问日期等资源会因为 GET 操作而自我更新,属于例外)。
POST
用于向服务器注册新建的资源,如新用户注册、发布新的博文等。
PUT
用于更新资源。PUT 会用发送的资源完全替换原有的资源信息。如果只是更新资源的某部分数据,可以使用
PATCH
。DELETE
用于删除指定的资源。
PATCH
用于更新原有资源中的部分信息。
使用连接符来连接多个单词 为什么是连字符(-)而不是下划线等呢?因为 URI 的主机名(域名)允许使用连字符而禁止使用下划线,且不区分大小写。其次点字符具有特殊含义。 其实最好的方法是尽量避免在 URI 中使用多个单词。比如,不用
popular_users
,而用users/popular
,或者用查询字符串的方式。分页的设计是否恰当 ① 获取数据量和获取位置的查询参数: 通过
per_page=50&page=3
或limit=50&offset=100
组合。page 一般从1开始计数,offet 则从 0 开始计数。但这种使用相对位置的方法存在以下几个问题:(1) 性能问题(为了获取第2302条开始的数据,也需要从首条数据开发计数) (2) 如果数据更新的频率很高,会导致当前获取的数据出现一定的偏差(如数据重复)。 ② 使用绝对位置来获取数据。如“某个 ID 之前”或“某个日期之前”等条件。登录有没有使用 OAuth 2.0
响应数据格式有没有使用 JSON 作为默认格式 越来越多公司只支持 JSON,而不支持 XML。
是否支持通过查询参数来指定数据格式 若希望支持或者必须支持其他数据格式,则通过查询参数(推荐键值为
format
)来指定。是否支持不必要的 JSONP 通过查询参数 callback 指定回调函数名字,另外由于 JSONP 是 JavaScript 而不是 JSON, Content-type 不是 application/json,而使用 application/javascript。 使用 JSONP 最大的问题在于服务器返回错误时无法正确应对。当返回错误的状态码(400等)时,script 元素就会终止脚本的载入。换言之,如果在处理 JSONP 时发生错误,返回了 4、5 字头的状态码,客户端方面就完全无法知晓当前发生了什么。 于是在使用 JSONP 时,即便发生了错误,也要求服务器依旧返回 200 这样的状态码,并在响应体里显示具体的错误内容。 案例——将原本置于首部的状态码等信息放到消息体里进行处理。
http://api.example.com/v1/users/12345?fields=name,age
{ "errors": [ { "messages": "Bad Authentication data", "code": 215 } ] }
{ "errors": { "developerMessage": "面向开发人员的信息", "userMessage": "面向用户的信息", "code": 2013, "info": "http://docs.example.com/api/v1/authentication" } }
主要的 HTTP 状态码