02月08, 2017

这个接口很RestFul

What's RESTful

REST:REpresentational State Transfer: 全称是 Resource Representational State Transfer:通俗来讲就是:资源在网络中以某种表现形式进行状态转移。分解开来:

  • Resource:资源,即数据(前面说过网络的核心)。比如 newsfeed,friends等;

  • Representational:某种表现形式,比如用JSON,XML,JPEG等;

  • State Transfer:状态变化。通过HTTP动词实现。

REST本身不实用,实用的是如何设计 RESTful API(REST风格的网络接口;

Why RestFul

WEB发展是前后端不分离(eg:PHP,JSP).近年来客户端的不断发展,RESTful可以统一一套接口为Web,IOS,Android提供服务。一些服务平台不需要显示地提供前端接口,于是RESTful更是最好的选择。

如何设计

  1. URL root:
    https://example.org/api/v1/*
    https://api.example.com/v1/*
    
  2. API versioning:

    可以放在URL里面,也可以用HTTP的header

    /api/v1/
    
  3. URI使用名词而不是动词,且推荐用复数

    用HTTP协议里的动词来实现资源的添加,修改,删除等操作。 “资源”是REST架构或者说整个网络处理的核心。

    BAD: /getProducts
    INSTEAD : GET /products
    
  4. 保证 HEAD 和 GET 方法是安全

    不会对资源状态有所改变(污染)。比如严格杜绝如下情

    GET /deleteProduct?id=1
    
  5. 其他

    • 警惕返回结果的大小。如果过大,及时进行分页(pagination)或者加入限制(limit)。HTTP协议支持分页(Pagination)操作,在Header中使用 Link 即可。
    • 使用正确的HTTP Status Code表示访问状态

      200 OK

      304 Not Modified

      400 Bad Request

      401 Unauthorized

      403 Forbidden

      404 Not Found

      500 Internal Server Error

    • 在返回结果用明确易懂的文本

    • 关于安全:自己的接口就用https,加上一个key做一次hash放在最后即可。

本文链接:http://inkzhou.com/post/about-restful.html

-- EOF --

Comments