restful api （转）

RESTful API

概述

参考地址

RESTful架构是一种流行的互联网软件架构，它结构清晰，符合标准，易于理解，扩展方便。
REST是Representational State Transfer的缩写，翻译为“表现层状态转化”。表现层其实就是资源，因此可以理解为“资源状态转化”。
网络应用上的任何实体都可以看作是一种资源，通过一个URI(统一资源定位符)指向它。

表现层（Representation）

“资源”是一种信息实体，它可以有多种外在表现形式。我们把“资源”具体呈现出来的形式叫做它的“表现层”。
例如，文本可以是txt格式表现，也可以用HTML格式，XML格式，JSON格式表现；图片可以是JPG格式也可以是PNG格式表现等。

URI之代表资源实体，不代表它的形式。URI应该之代表“资源”的位置，而它具体的表现形式应该在HTTP请求的头信息中用Accept和Content-Type字段指定，这两个字段才是对“表现层”的描述。

状态转化（State Transfer）

访问一个WEB应用就代表了客户端与服务短的一个互动过程。HTTP协议是一个无状态协议。因此所有的状态都保存在服务端。如果客户端想要操作服务器，就必须通过某种手段让服务端发生“状态变化”（State Transfer）。而这种状化是建立在表现层之上的，所以就是“表现层状态转化”。

总结什么是RESTful架构
  1. 每一个URI代表一种资源
  2. 客户端和服务端之间传递这种资源的某种表现层
  3. 客户端通过HTTP动词(GET,POST,PUT,DELETE)对服务端资源进行操作，实现表现层状态转换
典型的设计误区
  1. URI包含动词。“资源”是一种实体，应该是名词。URI不应该有动词，动词放在HTTP协议中。
  2. URI中加入版本号。例如

    http://www.example.com/app/1.0/foo
    http://www.example.com/app/1.1/foo
    http://www.example.com/app/2.0/foo

    不同的版本可以理解为同一种资源的不同表现形式，所以应该用同一个URI，版本号可以在HTTP请求头信息中的Accept字段中区分：

    Accept: vnd.example-com.foo+json; version=1.0
    Accept: vnd.example-com.foo+json; version=1.1
    Accept: vnd.example-com.foo+json; version=2.0

设计指南

协议

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

域名

应该尽量将API部署在专用域名之下。

https://api.example.com

如果确定API很简单，不会用进一步扩展，则可以考虑放在主域名下

https://example.org/api/

版本

应该将API的版本号放入URI

https://api.example.com/v1/

也可以放在HTTP头信息中，但不如仿如URI直观

路径

路径就是API的网址，每一个路径代表一种资源，所以路径只有名词不能有动词。而且所用的名词往往与数据库表名对应。一般而言，数据库中的表是记录的集合，因此API中的名词也应该使用复数。例如：

https://api.example.com/v1/zoos
https://api.example.com/v1/animals

HTTP动词

对于资源的具体操作，由HTTP动词表示
常用的HTTP动词包括一下几个，括号里是对应的SQL命令：

  • GET（SELECT）: 从服务器取出资源（一个或多个）
  • POST（CREATE）: 在服务器新建一个资源
  • PUT（UPDATE）: 在服务器更新资源（客户端提供改变后的完整资源，即更新整一个资源）
  • PATCH（UPDATE）: 在服务器更新资源（客户端提供改变的属性，即更新资源的部分属性）
  • DELETE（DELETE）: 从服务器删除资源

还有两个不常用的HTTP动词

  • HEAD: 获取资源的元数据
  • OPTIONS: 获取信息，关于资源的哪些属性是客户端可以改变的

下面是若干例子:

  • 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）

如果记录数过多，服务器不可能一次性将所有的信息返回给客户端。API应该提供参数，过滤返回结果。下面一些常见的参数：

  • ?limit=10：指定返回记录的数量
  • ?offset=10：指定返回记录的开始位置
  • ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序
  • ?animal_type_id=1：指定筛选条件

参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

状态码（Status Codes）

服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）

  • 200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）
  • 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功
  • 204 NO CONTENT - [DELETE]：用户删除数据成功
  • 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的
  • 404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的
  • 500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功

状态码的完整列表参见这里

错误处理

如果状态码是4XX，就应该向客户端返回出错信息。一般来说，返回的信息中将error作为键名。

{ error: "Invalid API key" }

返回结果

针对不同的操作，服务器想客户端返回的结果应该符合一下规范

  • GET /collection：返回资源对象的列表（数组）
  • GET /collection/resource：返回单个资源对象
  • POST /collection：返回新生成的资源对象
  • PUT /collection/resource：返回更新后完整的资源对象
  • PATCH /collection/resource：返回更新后完整的资源对象
  • DELETE /collection/resource：返回一个空文档

Hypermedia API

RESTful API最好做到Hypermedia，即返回结果中提供链接，指向其他API方法，是的用户不查文档，也知道该怎么做。比如，当用户向api.example.com的根目录发出请求，会得到这样一个文档：

{"link": {
"rel": "collection https://www.example.com/zoos",
"href": "https://api.example.com/zoos",
"title": "List of zoos",
"type": "application/vnd.yourformat+json"
}}

上面代码表示，文档中有一个link属性，用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系（collection关系，并给出该collection的网址），href表示API的路径，title表示API的标题，type表示返回类型

Hypermedia API的设计被称为HATEOAS。Github的API就是这种设计，访问api.github.com会得到一个所有可用API的网址列表

{
"current_user_url": "https://api.github.com/user",
"authorizations_url": "https://api.github.com/authorizations",
// ...
}

其他

    1. API的身份认证应该使用OAuth2.0框架
    2. 服务器返回的数据格式，应该尽量适应JSON，避免使用XML
时间： 2024-08-09 07:36:37

restful api （转）的相关文章

利用 Django REST framework 编写 RESTful API

利用 Django REST framework 编写 RESTful API Updateat 2015/12/3: 增加 filter 最近在玩 Django,不得不说 rest_framework 真乃一大神器,可以轻易的甚至自动化的搞定很多事情,比如: 自动生成符合 RESTful 规范的 API 支持 OPTION.HEAD.POST.GET.PATCH.PUT.DELETE 根据 Content-Type 来动态的返回数据类型(如 text.json) 生成 browserable

Yii2框架RESTful API教程（二） - 格式化响应，授权认证和速率限制

之前写过一篇Yii2框架RESTful API教程(一) - 快速入门,今天接着来探究一下Yii2 RESTful的格式化响应,授权认证和速率限制三个部分 一.目录结构 先列出需要改动的文件.目录如下: web ├─ common │ └─ models │ └ User.php └─ frontend ├─ config │ └ main.php └─ controllers └ BookController.php 二.格式化响应 Yii2 RESTful支持JSON和XML格式,如果想指定

flask开发restful api

在此之前,向大家说明的是,我们整个框架用的是flask + sqlalchemy + redis.如果没有开发过web,还是先去学习一下,这边只是介绍如果从开发web转换到开发移动端.如果flask还不是很熟悉,我建议先到这个网站简单学习一下,非常非常简单.http://dormousehole.readthedocs.org/en/latest/ 一直想写一些特别的东西,能让大家学习讨论的东西.但目前网上的很多博客,老么就按照官方文档照本宣读,要么直接搬代码,什么都不说明.我写这个系列的博客,

[CI] 使用CodeIgniter框架搭建RESTful API服务

在2011年8月的时候,我写了一篇博客<使用CodeIgniter框架搭建RESTful API服务>,介绍了RESTful的设计概念,以及使用CodeIgniter框架实现RESTful API的方法.转眼两年过去了,REST在这两年里有了很大的改进.我对于前一篇博客中的某些方面不是很满意,所以希望能利用这次机会写一个更加完善的版本.我的项目基于Phil Sturgeon的CodeIgniter REST Server,遵循他自己的DBAD协议.Phil的这个项目很棒,干净利落,简单实用,并

3.Spring Boot中使用Swagger2构建强大的RESTful API文档

原文:http://www.jianshu.com/p/8033ef83a8ed 由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这些终端会共用很多底层业务逻辑,因此我们会抽象出这样一层来同时服务于多个移动端或者Web前端. 这样一来,我们的RESTful API就有可能要面对多个开发人员或多个开发团队:IOS开发.Android开发或是Web开发

理解restful API

简介 随着Web开发的不断开发, 低耦合的需求被提上了日程, 催生出了前后端分离的方案. 前后端分离使前端和服务器端相互独立, 细化前后端开发, 于是近几年API架构风行. RESTful架构由Roy Fielding在一篇博士论文中提出. `REST, 即Representational State Transfer的缩写, 中文可以译为表现层状态转化 表现层可以理解为资源的表现层, 资源在网络通信中无处不在, 一段文本, 一张图片, 一个文档都是资源, JSON是现在最常用的资源表示格式.

开发restful api总结的几点小经验

与其说是开发,不如说是打补丁! 是个jesery+spring的restful service,加了一个权限校验部分,做了一些调整. 本来其实很简单的一个事,后来发现,这个代码太霸道.本来传个参数是action_id 这个东西,结果参数名字有如下:action_id,actionID,id 我只能说傻傻分不清楚到底你传的什么, 因为还有其他id,参数名字参考刚才的. 代码中的也是混乱,虽然我知道有很多先人在修改了,但是也不至于这样吧. 吐槽完毕. 1.N次开发restful api主意版本迭代,

拿nodejs快速搭建简单Oauth认证和restful API server攻略

拿nodejs快速搭建简单Oauth认证和restful API server攻略:http://blog.csdn.net/zhaoweitco/article/details/21708955 最近一直在鼓捣这个东西,拿出来分享下一下经验吧,其实很简单,一点也不难. 首先需求是这样,给自己的网站要增加API服务,API分为两种,公共的和私有授权的,授权的使用Oauth方法认证身份,API格式均为JOSN和JSONP. 嗯,别的语言我也没怎么学过,首先是找合适的框架进行实现吧.本身网站使用的e

RESTful API 设计指南（转）

网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备......). 因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信.这导致API构架的流行,甚至出现"API First"的设计思想.RESTful API是目前比较成熟的一套互联网应用程序的API设计理论.我以前写过一篇<理解RESTful架构>,探讨如何理解这个概念. 今天,我将介绍RESTful API的设计细节,探讨如何设计一套合理.好用的API