码迷,mamicode.com
首页 > 其他好文 > 详细

RESTful规范

时间:2019-11-26 21:08:43      阅读:81      评论:0      收藏:0      [点我收藏+]

标签:example   authorize   auth   not found   形式   用户   ble   资源   识别   

什么是RESTful?

Representational State Transfer , 中文翻译为“表征状态转移” 。

Resource(资源): 对象的单个实例,是一个具体的实在。可以用一个URI(统一资源定位符)指向它,每种资源对应一个特定的URI。要获取这个资源,访问它的URI就可以,因此URI就成了每一个资源的地址或独一无二的识别符。

表现层(Representation) :"资源"是一种信息实体,它可以有多种外在表现形式。我们把"资源"具体呈现出来的形式,叫做它的"表现层"(Representation)。

状态转化(State Transfer) : 互联网通信协议HTTP协议,是一个无状态协议。这意味着,所有的状态都保存在服务器端。因此,如果客户端想要操作服务器,必须通过某种手段,让服务器端发生"状态转化"(State Transfer)。 客户端用到的手段,只能是HTTP协议。 就是在HTTP协议里面,用四个表示操作方式的动词: GET、POST、PUT、DELETE。它们分别对应四种基本操作:GET用来获取资源,POST用来新建资源(也可以用于更新资源),PUT用来更新资源,DELETE用来删除资源。

所有的数据,不过是通过网络获取的数据,都是资源,将一切数据视为资源是REST区别与其他架构风格的最本质属性。

对于REST这种面向资源的架构风格,有人提出一种全新的结构理念,即:面向资源架构(ROA:Resource Oriented Architecture)。

RESTful API设计规范

restful是一个API接口的规则,是程序进行数据交换的约定。

  1. 建议用https代替http,保证数据传输的安全。

  2. 在URL中体现api,添加api标识,

    https://www.xxx.com/api/p/xxx/   # 建议,不存在跨域
    https://api.xxx.com/p/xxx
    版本还可以放在请求头。
  3. 在URL中体现版本(便于版本迭代)

    https://www.xxx.com/api/v1/p/xxx/    # v1版本
  4. restful是面向资源编程,网络上的一切都是资源,因此一般情况下对于api接口,用名词,不用动词。

    https://www.xxx.com/api/v1/userinfo/
  5. 如果有加入筛选条件的话,可以在URL后面进行传递。

    /?page=1&xxx=2
  6. 根据method不同做不同操作,之前使用4个URL,现在只需使用一个。

    get/post/put/patch/delete
    
    GET    :从服务器取出资源(一项或多项)
    POST   :在服务器新建一个资源
    PUT    :在服务器更新资源(客户端提供改变后的完整资源)
    PATCH  :在服务器更新资源(客户端提供改变的属性,局部更新)
    DELETE :从服务器删除资源
  7. 返回给用户状态码 200 301/302 400 500

    data_info = {"code": 10001, 'data': random_string}
    return Response(data_info)
    
    # 常用状态码:
    200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
    201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
    202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
    204 NO CONTENT - [DELETE]:用户删除数据成功。
    301/302:永久重定向/临时重定向
    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 - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。
  8. 返回值, 针对不同操作,服务器向用户返回的结果应该符合以下规范。

    GET /collection:返回资源对象的列表(数组)
    GET /collection/resource:返回单个资源对象
    POST /collection:返回新生成的资源对象
    PUT /collection/resource:返回完整的资源对象
    PATCH /collection/resource:返回完整的资源对象
    DELETE /collection/resource:返回一个空文档
  9. 操作异常,要返回错误信息, error当做key。

    {error: 'Invalid API Key'}
  10. Hypermedia API,RESTful API最好做到Hypermedia,即返回结果中提供链接,连向其他API方法,使得用户不查文档,也知道下一步应该做什么。

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

RESTful规范

标签:example   authorize   auth   not found   形式   用户   ble   资源   识别   

原文地址:https://www.cnblogs.com/yzm1017/p/11938439.html

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!