如何设计RESTful API

Myth丶恋晨 2022-05-22 11:09 244阅读 0赞

每次开工前，设计API也是十分重要的一个环节，现在RESTful API大行其道，那么如何才能设计出好的RESTful API呢，也就是说我们在设计RESTful API需要遵循哪些原则呢？

### 1、使用名词，别使用动词 ###

我们知道RESTful API是一种面向资源（resource）设计的API，那么既然是面向资源，那自然用名词更合适，这个比较好理解吧。

/computers #推荐
    /run       #不推荐

### 2、既然用名词，那就用名词的复数形式，当然不可数名词可以不变形 ###

感觉有点在讲英语语法，这样做的目的其实就是为了避免与单数搞混淆，为了方便起见，索性都用复数。再多提一点，这里尽量用一个单词表示资源，不要用多个单词，然后中间加个下划线，比如`/student_name/`这样是不推荐的，如果是参数的话，这个可以，比如

/products/{product_id}/versions

### 3、用层级关系表示父子资源 ###

啥意思呢，就比如上面这个api，`products`就是父级资源，而`versions`则是子级资源，意思就是某个产品下面现在所有的版本，比如Microsoft Windows，这是父级资源，作为子级资源的versions则可以是10，8，7，vista等等。

### 4、GET和一些用于查询的参数不应该对状态做修改 ###

这个很容易理解，GET和查询本来就是读的操作，读就好好读，别管其他的事情，其他可以用PUT，POST和DELETE这些方法来做。

### 5、对于GET要提供过滤，排序，选择特定field和分页的功能 ###

这个从用户角度也不难理解，这些可以用参数来搞定，比如：  
过滤可以这么做:

GET /cars?color=red

排序的话可以指定根据哪个属性排序：

GET /cars?sort=-color

只选择部分属性：

GET /cars?fields=manufacturer,model,id,color

分页一般这么做：

/orders?limit=25&offset=50

### 6、指定版本 ###

有时候api也有更新，所以给个版本还是很有必要的。一般来说只用大版本就好了，比如v1，v2这样的，像v1.2，v2.5.1这样的就算了。

/api/v1/products/{product_id}/versions

### 7、用Http状态码来处理错误 ###

错误是避免不了的，但是出了错误就得积极去处理，那么我们可以用http状态码来表示这些错误，比如：

*  2XX -OK
 *  3XX-未修改
 *  4XX-这种经常见，比如404-找不到资源，403-禁止，还有几个大家可以去查，这里就不展开了。
 *  5XX-服务器错误

如果想让错误信息更加详细，那就加一个错误的payload，比如：

{
      "errors": [
       {
        "userMessage": "Resource does not exist",
        "internalMessage": "ERROR in the database",
        "code": 404,
        "more info": "http://dev.csdn.net/blog/api/v1/errors/12345"
       }
      ]
    }

### 8、用HATEOAS（Hypermedia as the Engine of Application State） ###

翻译过来就是超媒体作为应用状态的引擎，啥意思呢，资源中有超链接的话，应该是链接也指向资源

{
      "id": 711,
      "manufacturer": "bmw",
      "model": "X5",
      "seats": 5,
      "drivers": [
       {
        "id": "23",
        "name": "Stefan Jauker",
        "links": [
         {
         "rel": "self",
         "href": "/api/v1/drivers/23"
        }
       ]
      }
     ]
    }

### 9、用HTTP header作为序列格式 ###

服务器和客户端需要通信，就得知道彼此的格式，那么就使用HTTP的header。

*Content-Type* 定义请求格式  
*Accept* 定义响应格式

### 10、允许重载HTTP方法 ###

有时候代理只支持POST和PUT，其他的统统都没有，那么为了设计RESTful API，API就得设法重载HTTP方法，比如；这时候可以用自定义的HTTP Header *X-HTTP-Method-Override* 来重载POST。

设计API的时候注意到了这些，大概也就差不多了，但我相信有些十分重要的做法可能还是没提到，欢迎大家不吝赐教。