RESTful API 编写指南

## 一、协议

* * * API与用户的通信协议，先使用 HTTP 协议

* * * 后期考虑升级成 HTTPS 协议

## 二、URl

* * * URl规范

1.不用大写；

2.用中杠 - 不用下杠 _ ；

3.参数列表要encode；

4.URl中的名词表示资源集合，使用复数形式。

5.在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词（特殊情况可以使用动词），而且所用的名词往往与数据库的表格名对应。

* * * 资源集合 vs单个资源

URI表示资源的两种方式：资源集合、单个资源。

资源集合：

       /zoos / 所有动物园

       /zoos/1/animals / id为1的动物园中的所有动物

单个资源：

       /zoos/1/ id为1的动物园

       /zoos/1;2;3/ id为1，2，3的动物园

 

* * * 避免层级过深的URl

在url中表达层级，用于 按实体关联关系进行对象导航 ，一般根据id导航。

过深的导航容易导致url膨胀，不易维护，如 GET /zoos/1/areas/3/animals/4 ，尽量使用查询参数代替路径中的实体导航，如 GET/animals?zoo=1&area=3 ；

 

## 三、版本

应该将API的版本号放入到URI中

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

## 四、路径（Endpoint）

* * * 路径又称"终点"（endpoint），表示A