zoukankan      html  css  js  c++  java
  • 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
  • 相关阅读:
    c:forTokens标签循环输出
    jsp转long类型为date,并且格式化
    spring中@Param和mybatis中@Param使用区别(暂时还没接触)
    734. Sentence Similarity 有字典数组的相似句子
    246. Strobogrammatic Number 上下对称的数字
    720. Longest Word in Dictionary 能连续拼接出来的最长单词
    599. Minimum Index Sum of Two Lists两个餐厅列表的索引和最小
    594. Longest Harmonious Subsequence强制差距为1的最长连续
    645. Set Mismatch挑出不匹配的元素和应该真正存在的元素
    409. Longest Palindrome 最长对称串
  • 原文地址:https://www.cnblogs.com/rhett-web/p/4909703.html
Copyright © 2011-2022 走看看