读RESTful API 设计指南心得体会
为什么80%的码农都做不了架构师?>>>
读阮大神的两篇文章心得以及其他一些文章的体会:
- RESTful API 设计指南
- 理解RESTful架构
- REST接口设计规范
URL
- url代表一种资源,不要用动词,应该用名词复数,"/"不应该出现在URL的末尾
- api应该使用专用的域名,如果api简单,可以部署到主域名下,如:
https://example.org/api/
- 尽量使用
HTTPs协议
- 版本:一是放url,二是放HTTP头信息,Github采用第二种做法
HTTP动词,对应 CRUD操作:
- GET /zoos:列出所有动物园
- POST /zoos:新建一个动物园
- GET /zoos/ID:获取某个指定动物园的信息
- PUT /zoos/ID:更新某个指定动物园的信息(提供该动物园的全部信息)
- PATCH /zoos/ID:更新某个指定动物园的信息(提供该动物园的部分信息)
- DELETE /zoos/ID:删除某个动物园
- GET /zoos/ID/animals:列出某个指定动物园的所有动物
- DELETE /zoos/ID/animals/ID:删除某个指定动物园的指定动物
过滤信息(Filtering)
- ?limit=10:指定返回记录的数量
- ?offset=10:指定返回记录的开始位置。
- ?page=2&per_page=100:指定第几页,以及每页的记录数。
- ?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
- ?animal_type_id=1:指定筛选条件:参数的设计允许存在冗余,即允许API路径和URL参数偶尔有重复。比如,GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。
HTTP状态(Status Codes)详见:https://my.oschina.net/kmwzjs/blog/747335
- 200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
- 201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
- 202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
- 204 NO CONTENT - [DELETE]:用户删除数据成功。
- 400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。
- 401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。
- 403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。
- 404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。
- 406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
- 410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。
- 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
- 500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。
错误处理(Error handling)
- 如果状态码是4xx,就应该向用户返回出错信息。一般来说,返回的信息中将error作为键名,出错信息作为键值即可。
{error: "Invalid API key"
}
返回结果
- GET /collection:返回资源对象的列表(数组)
- GET /collection/resource:返回单个资源对象
- POST /collection:返回新生成的资源对象
- PUT /collection/resource:返回完整的资源对象
- PATCH /collection/resource:返回完整的资源对象
- DELETE /collection/resource:返回一个空文档
身份认证及返回数据格式
- API的身份认证应该使用 OAuth 2.0 框架
- 服务器返回的数据格式,应该尽量使用JSON,避免使用XML
转载于:https://my.oschina.net/kmwzjs/blog/747342
读RESTful API 设计指南心得体会相关推荐
- RESTful API 设计指南[转]
一种软件架构风格.设计风格,而不是标准,只是提供了一组设计原则和约束条件.它主要用于客户端和服务器交互类的软件.基于这个风格设计的软件可以更简洁,更有层次,更易于实现缓存等机制. RESTful AP ...
- RESTful API 设计指南 (转)
RESTful API 设计指南 2016-02-23 ImportNew (点击上方公号,可快速关注) 作者:阮一峰 链接:http://www.ruanyifeng.com/blog/2014/0 ...
- RESTful API 设计指南
原文地址:http://www.ruanyifeng.com/blog/2014/05/restful_api.html RESTful API 设计指南 作者: 阮一峰 日期: 2014年5月22日 ...
- RESTful API 设计指南(转)
一.协议 API与用户的通信协议,总是使用HTTPs协议. 二.域名 应该尽量将API部署在专用域名之下. https://api.example.com 如果确定API很简单,不会有进一步扩展,可以 ...
- 我是如何根据豆瓣api来理解Restful API设计的
1.什么是REST REST全称是Representational State Transfer,表述状态转移的意思.它是在Roy Fielding博士论文首次提出.REST本身没有创造新的技术.组件 ...
- Restful API 设计
1. 简介 目前 "互联网软件"从用客户端/服务端模式,建立在分布式体系上,通过互联网通讯,具有高延时.高开发等特点.但是软件开发和网络是两个不同的领域,交集很少.要使得两个融合, ...
- RESTful API设计简介
1.什么是REST REST全称是Representational State Transfer,中文意思是表述性状态转移. 它首次出现在2000年Roy Fielding的博士论文中,Roy Fie ...
- RESTful API 设计、文档生成、测试
参考资料 理解RESTful架构 RESTful API 设计指南 REST API 使用详解 文档工具 API Blueprint RAML Swagger ReadMe Mock API JSON ...
- RESTful API设计技巧经验总结
原文:RESTful API Design Tips from Experience 作者:Peter Boyer 翻译:雁惊寒 译者注:本文是作者在自己的工作经验中总结出来的RESTful API设 ...
- 服务端指南 | 良好的 API 设计指南
设计一套良好的 API 接口. 原文地址:服务端指南 | 良好的 API 设计指南 博客地址:blog.720ui.com/ 版本号 在 RESTful API 中,API 接口应该尽量兼容之前的版本 ...
最新文章
- Windows Phone 8 蓝牙标准
- oracle 11g 忘记了sys,system,scott密码
- html标签强制转换位置,王老师html零基础学习笔记第4课——样式初始化+类型转化...
- golang延时_golang 实现延迟消息原理与方法
- sqlserver建表语句_重新认识MySQL中的COUNT语句
- VSCode摸鱼插件 — FreeWindow
- 华为或正与联发科、紫光展锐就采购更多芯片事宜展开磋商
- php zmq demo1
- ENVI5.3.1使用Landsat 8影像进行预处理及分析实例操作
- 硬件开发笔记(七): 硬件开发基本流程,制作一个USB转RS232的模块(六):创建0603封装并关联原理图元器件
- web测试,APP测试和小程序测试特点
- android 国家代码
- 当下OA系统的使用缺陷以及相关解决方案
- 云上城之个服务器维护时间,云上城之歌开服时间表 官方最新开服情况
- 机械臂抓取学习笔记二
- Neo4j构建目标知识图谱
- 使用autohotkey创建win10虚拟桌面切换快捷键
- android 相册png黑底,Android png透明图片转jpg时背景变黑的解决方法
- javaFX裁剪视频exe
- python yolo 视频人头计数人流量监测景区教室人头检测