本文参考自:http://www.ruanyifeng.com/blog/2014/05/restful_api.html,http://www.dongming8.cn/?p=590

服务器端:

1. JSON形式:

请求method 含义 api建议格式(url) v1-版本号,  成功返回值 失败码(典型) 备注
PUT

修改数据请求

(客户端提供改变后的完整资源)

/v1/collection/ID 完整的对象信息(JSON格式)

201(Updated)

403(Forbidden)

500(ServerError)

 
POST 创建数据请求 /v1/collection/ID 新创建的完整的对象信息(JSON格式)

201(Created)

403(Forbidden)

500(ServerError)

 
DELETE 删除数据请求 /v1/collection/ID 空文档

403(Forbidden)

500(ServerError)

 
GET 读取数据请求

/v1/collection/ID

or

/v1/collection/?limit=n?offset=10?page=2&per_page=100?sortby=name&order=asc?animal_type_id=1

单个资源对象

or

资源对象的列表(数组)

200(OK)

404(NotFound)

410(Gone)

 
PATCH 

修改数据请求

(客户端提供改变的属性)

/v1/collection/ID 完整的对象信息(JSON格式)

201(Updated)

403(Forbidden)

500(ServerError)

 
     以下比较少用到
HEAD 获取资源的元数据        
OPTIONS

获取信息,

客户端可修改属性集。

       
           

可发现性(discoverability)

无论成功还是失败,最好附有一个link字段,用于标注相关的api,提示用户下一步可以做什么,如下:

{

"link": {
"rel": "collection https://www.example.com/zoos",//这个API与当前网址的关系
"href": "https://api.example.com/zoos",//api地址
"title": "List of zoos",//api标题
"type": "application/vnd.yourformat+json"//api返回值类型
} }

错误返回消息的一般格式:

{
'code':1234,//错误代码
'message':'错误消息',
'descrpition':'详细信息',//简单描述,可用于GET/DELETE请求。或者以下字段
'errors'://用于更详细的针对栏位的提示,通常用于POST/PATCH/PUT请求
[
{
'code':3122,//代码
'field':'具体字段',
'message':'具体原因',
},
...
]
}

当然,也应该根据具体情况具体定义格式。  

错误消息应当以200的状态码返回么?不应该,参考这里

当发生错误的时候,通常正常的返回对应的状态码。

补充:

API与用户的通信协议,总是使用HTTPs协议

API的身份认证应该使用OAuth 2.0框架。

rest api设计的一般原则的更多相关文章

  1. javascript的api设计原则

    前言 本篇博文来自一次公司内部的前端分享,从多个方面讨论了在设计接口时遵循的原则,总共包含了七个大块.系卤煮自己总结的一些经验和教训.本篇博文同时也参考了其他一些文章,相关地址会在后面贴出来.很难做到 ...

  2. GOTO Berlin: Web API设计原则

    在邮件列表和讨论区中有很多与REST和Web API相关的讨论,下面仅是我个人对这些问题的一些见解,并没有绝对的真理,InnoQ的首席顾问Oliver Wolf在GOTO Berlin大会上开始自己的 ...

  3. Atitit. Api 设计 原则 ---归一化

    Atitit. Api 设计 原则 ---归一化 1.1. 叫做归一化1 1.2. 归一化的实例:一切对象都可以序列化/toString  通过接口实现1 1.3. 泛文件概念.2 1.4. 游戏行业 ...

  4. 优秀API设计的十大原则

    优秀API设计的十大原则 2015-09-23    分类:编程开发.设计模式.首页精华暂无人评论 分享到:更多4 二十万年薪PHP工程师培养计划 成为被疯抢的Android牛人 风中叶讲Java重难 ...

  5. API设计原则

    译序 Qt的设计水准在业界很有口碑,一致.易于掌握和强大的API是Qt最著名的优点之一.此文既是Qt官网上的API设计指导准则,也是Qt在API设计上的实践总结.虽然Qt用的是C++,但其中设计原则和 ...

  6. API设计原则(觉得太合适,转发做记录)

    API设计原则 对于云计算系统,系统API实际上处于系统设计的统领地位,正如本文前面所说,K8s集群系统每支持一项新功能,引入一项新技术,一定会新引入对应的API对象,支持对该功能的管理操作,理解掌握 ...

  7. 好的框架需要好的 API 设计 —— API 设计的六个原则

    说到框架设计,打心底都会觉得很大很宽泛,而 API 设计是框架设计中的重要组成部分.相比于有很多大佬都认可的面向对象的六大原则.23 种常见的设计模式来说,API 设计确实缺少行业公认的原则或者说设计 ...

  8. RESTful API设计原则与规范

    RESTful API设计原则与规范 一.背景与基础概念 2 二.RESTful API应遵循的原则 3 1.协议(Protocol) 3 2.域名(ROOT URL) 3 3.版本(Versioni ...

  9. 【JS】327- javascript 的 api 设计原则

    点击上方"前端自习课"关注,学习起来~ 前言 本篇博文来自一次公司内部的前端分享,从多个方面讨论了在设计接口时遵循的原则,总共包含了七个大块.系卤煮自己总结的一些经验和教训.本篇博 ...

随机推荐

  1. codeforces 709B Checkpoints

    题目链接:http://codeforces.com/problemset/problem/709/B 题目大意: 第一行给出两个数 n,x.第二行 输入 n 个数. 要求:从x位置遍历 n-1 个位 ...

  2. HTMl5结构元素:article

    article: 表示文档.页面.应用程序或站点中的自包含成分所构成的一个页面的一部分,并且这部分专用于独立地分类或复用.(例如:一个博客的帖子,一篇文章,一个视频文件等.)和<nav>一 ...

  3. ASP.NET WebForm中用async/await实现异步

    1. 在.aspx中添加异步标记 <%@ Page Language="C#" Async="true"%> 2. 在.aspx.cs或者.ascx ...

  4. linq 多表分组查询统计

    var q1 = from orderitem in q2 join pd in _iProductDetailContract.Entities on orderitem.ProductDetail ...

  5. Orchard源码分析(5.2):BeginRequest事件处理(DefaultOrchardHost.BeginRequest方法)

    BeginRequest事件处理的作用是确保所有Shell已经加载,或者在扩展有变化的时候重新加载.          void IOrchardHost .BeginRequest() {      ...

  6. ASP.NET MVC 表单提交List到Controller

    1.实体结构: 2.View代码: 3.controller代码: 参考链接:http://shiyousan.com/post/635383025861004585

  7. 30 分钟开发一个简单的 watchOS 2 app <oneVcat>

    Apple Watch 和 watchOS 第一代产品只允许用户在 iPhone 设备上进行计算,然后将结果传输到手表上进行显示.在这个框架下,手表充当的功能在很大程度上只是手机的另一块小一些的显示器 ...

  8. JAVA日期加减运算

    1.用java.util.Calender来实现 Calendar calendar=Calendar.getInstance();      calendar.setTime(new Date()) ...

  9. 如何运行python

    如何运行Python程序 不少新手朋友遇到的第一个问题,不是Python的数据结构,不是Python的类库使用,更不是第三方模块.框架的应用,而是简单的“如何运行”!Python可用以下三种方式运行, ...

  10. Java-Linux系统中搭建开发环境

    准备工作: 0.虚拟机中的系统→{RHEL-I386} 1.JDK→{首先要知道下载哪个版本" [zf@string ~]$ getconf LONG_BIT ":".t ...