专栏首页LNMP开发那些事restful api设计最佳实践

restful api设计最佳实践

参考github的api,总结一份实践经验,方便以后设计api查阅。

使用https

考虑api的安全性,建议使用https访问。 证书可使用let’s encrypt的免费证书。

api访问地址与版本

访问地址使用统一的api前缀,或者使用二级域名,版本号建议显式的放在url中。 例如: https://www.iian.xyz/api/v1/users

交互结构

尽量采用json,提供替他类型的内容,使用accept声明可响应格式。客户端使用content-type来标记使用的格式。

url设计

操作针对资源进行,使用url来代表资源,使用http请求方法来指明进行的操作。 例如:

// 查询用户列表
GET: https://www.iian.xyz/api/v1/users
// 删除用户
DELETE: https://www.iian.xyz/api/v1/users/1
// 添加用户
POST: https://www.iian.xyz/api/v1/users
// 修改用户信息
PUT: https://www.iian.xyz/api/v1/users/1

查询与筛选

查询与筛选使用查询字符串。 例如:GET: https://www.iian.xyz/api/v1/users?page=1&per_page=10&keywords=aaa

响应信息

错误必须同时发送错误信息。 根据执行情况,选择对应的状态码进行返回。可以使用自定义的状态码,但是也应该同时指明响应的状态码。具体的响应状态码含义可以,可以访问这个网站

身份信息验证与权限验证

没有携带约定的身份信息,应该返回401。

401 UNAUTHORIZED The request has not been applied because it lacks valid authentication credentials for the target resource. The server generating a 401 response MUST send a WWW-Authenticate header field1 containing at least one challenge applicable to the target resource. If the request included authentication credentials, then the 401 response indicates that authorization has been refused for those credentials. The user agent MAY repeat the request with a new or replaced Authorization header field2. If the 401 response contains the same challenge as the prior response, and the user agent has already attempted authentication at least once, then the user agent SHOULD present the enclosed representation to the user, since it usually contains relevant diagnostic information.

而对于没有权限执行某个操作,建议使用404,防止嗅探。

404 NOT FOUND The origin server did not find a current representation for the target resource or is not willing to disclose that one exists. A 404 status code does not indicate whether this lack of representation is temporary or permanent; the 410 Gone status code is preferred over 404 if the origin server knows, presumably through some configurable means, that the condition is likely to be permanent. A 404 response is cacheable by default; i.e., unless otherwise indicated by the method definition or explicit cache controls1.

限速、限流

对于接口的访问次数、流量限制,超过后建议使用429。

The user has sent too many requests in a given amount of time (“rate limiting”). The response representations SHOULD include details explaining the condition, and MAY include a Retry-After header indicating how long to wait before making a new request. Note that this specification does not define how the origin server identifies the user, nor how it counts requests. For example, an origin server that is limiting request rates can do so based upon counts of requests on a per-resource basis, across the entire server, or even among a set of servers. Likewise, it might identify the user by its authentication credentials, or a stateful cookie. Responses with the 429 status code MUST NOT be stored by a cache.

文档

文档应该声明接口的访问方法,接口地址,应该携带的请求头信息,响应格式,响应内容举例,错误码以及接口的使用场景。

文章作者ianzhi,原文地址:https://www.dnote.cn/users/ianzhi/posts/restfulapishejizuijiashijian

文章版权归作者所有,转载请保留此声明。

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • docker安装lnmp环境

    文章作者ianzhi,原文地址:https://www.dnote.cn/users/ianzhi/posts/docker-install-lnmp-env

    ianzhi
  • laravel框架发送邮件配置

    我最开始配置,感觉配置都没有问题,最后发现是因为服务器安全组没有打开。所以,在配置之前,建议检查一下服务器是否打开25或者465端口。 检查项目主要包括fire...

    ianzhi
  • 硬刚苹果微软?!谷歌发布x86二合一平板电脑—Pixel Slate

    1. 外观方面,Pixel Slate采用深蓝配色,机身使用铝材,厚度仅7毫米左右,极致超薄,重量约为725克。

    ianzhi
  • 聊聊storm的WindowedBoltExecutor

    storm-2.0.0/storm-client/src/jvm/org/apache/storm/topology/WindowedBoltExecutor....

    codecraft
  • R Programming week2 Functions and Scoping Rules

    When R tries to bind a value to a symbol,it searches through a series of environ...

    统计学家
  • Duke@coursera 数据分析与统计推断unit5 inference for categorical variables

    一、sampling variability & CLT for proportions

    统计学家
  • 【easeljs】事件汇总

    文章说明:为了方便我自己查找easeljs的所有事件,所以我从easeljs的文档里抄过来加上自己的翻译,会慢慢补全,漏了的,错了的,评论一下我会补上去哦。(不...

    黒之染
  • nano:基本操作

    JNingWei
  • Fix Notification Switching Position Issue

    I once faced with a problem. I wrote a piece of code related with notifcation. E...

    技术小黑屋
  • Gazebo機器人仿真學習探索筆記(一)安裝與使用

    Gazebo提供了多平臺的安裝和使用支持,大部分主流的linux,Mac以及Windows,這裏結合ROS以Ubuntu爲例進行介紹。

    zhangrelay

扫码关注云+社区

领取腾讯云代金券