RESTful接口设计相关

发表于 更新于 分类于 阅读次数： 本文字数： 849 阅读时长 ≈ 1 分钟

网上看到的一些原则，记录一下，备查。

  1. api与用户通信总是使用HTTPS协议：https://api.github.com；
  2. 尽量将API部署在专属域名下，https://api.github.com；加入API很简单，不会有扩展，则可以考虑放到主域名下，例如https://www.github.com/api;
  3. 版本号放在url中，https://developer.github.com/v3；或将版本号放在头信息中，例如访问https://api.github.com的REST（V3版本）时，Accept: application/vnd.github.v3+json；
  4. api网址，或者说是endpoint，每个endpoint代表一种资源，这也是路径不能为动词的原因：用户https://api.github.com/users；某个用户某个仓库的issue**https://api.github.com/repos/username/repo_name/issues?parameter=val; 某个用户的仓库https://api.github.com/user/repos；
  5. URL定位资源；http动词表示操作；status code 表示操作结果：2XX成功、3XX重定向、4XX客户端错误、5XX服务器错误；
  6. Timestamps: ISO-8601
  7. Error handling

GET 返回码：200 (OK) + 404 (NOT FOUND) +400 (BAD REQUEST)
POST 返回码：200 (OK) or 201 (CREATED)
PUT 返回码：200 (OK) + 404 (NOT FOUND) +400 (BAD REQUEST) 409 Conflict
DELETE 返回码：200 (OK)

Authentication

  1. OAuth2
  2. api_key: api.geocod.io/v1/geocode?q=42370 Bob Hope Drive, Rancho Mirage CA&api_key=YOUR_API_KEY