restfulapi设计指南-java开发java经验技巧

《restfulapi设计指南-java开发java经验技巧》由会员上传分享，免费在线阅读，更多相关内容在工程资料-天天文库。

1、RESTfulAPI设计指南-编程开发技术RESTfulAPI设计指南原文出处：阮一峰网络应用程序，分为前端和后端两个部分。当前的发展趋势，就是前端设备层出不穷(手机、平板、桌面电脑、其他专用设备……)。因此，必须有一种统一的机制，方便不同的前端设备与后端进行通信。这导致API构架的流行，甚至出现”APIFirst"的设计思想。RESTfulAPI是目前比较成熟的一套互联网应用程序的API设计理论。我以前写过一篇《理解RESTful架构》，探讨如何理解这个概念。今天，我将介绍RESTfulAPI的设计细节

2、，探讨如何设计一套合理、好用的API。我的主要参考了两篇文章(1,2)。一、协议API与用户的通信协议，总是使用HTTPs协议。二、域名应该尽量将API部署在专用域名ZKohttps://api.example.com如果确定API很简单，不会有进-步扩展，可以考虑放在主域名下。https://example.org/api/三、版本(Versioning)应该将API的版本号放入URLohttps://api.example.com/vl/另一种做法是，将版木号放在HTTP头信息中，但不如放入URL方便

3、和直观oGithub采用这种做法。四、路径(Endpoint)路径又称”终点”(endpoint),表示API的具体网址。在RESTful架构屮，每个网址代表一种资源(resource),所以网址屮不能冇动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数拯库中的表都是同种记录的”集合”(collection),所以API中的名词也应该使用复数。举例来说，有一个API提供动物园(zoo)的信息，述包括各种动物和雇员的信息，则它的路径应该设计成下面这样。https://api.exampl

4、e.com/vl/zooshttps://api.example,com/vl/animalshttps://api.example.com/vl/employees五、HTTP动词对于资源的具体操作类型，由HTTP动词表示。常用的HTTP动词有下面五个(括号里是对应的SQL命令)。•GET(SELECT)：从服务器取出资源(一项或多项)。•POST(CREATE)：在服务器新建一个资源。•PUT(UPDATE)：在服务器更新资源(客户端提供改变后的完整资源)。•PATCH(UPDATE)：在服务器更新资

5、源(客户端提供改变的属性)。•DELETE(DELETE)：从服务器删除资源。述有两个不常用的HTTP动词。•HEAD：获取资源的元数据。•OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。下面是一些例子。•GET/zoos：列出所有动物园•POST/zoos：新建一个动物园•GET/zoos/ID：获取某个指定动物园的信息•PUT/zoos/ID：更新某个指定动物园的信息(提供该动物园的全部信息)•PATCH/zoos/ID：更新某个指定动物园的信息(提供该动物园的部分信息)•DELETE

6、/zoos/ID:删除某个动物园•GET/zoos/ID/animals：列出某个指定动物园的所有动物•DELETE/zoos/ID/animals/ID：删除某个指定动物园的指定动物六、过滤信息(Filtering)如果记录数量很多，服务器不可能都将它们返回给用户。API应该捉供参数，过滤返冋结果。下面是一些常见的参数。•?limit=10：指定返回记录的数量•?offset=10：指定返回记录的开始位置。•?page=2&per_page=100:指定第儿页，以及每页的记录数。•?sortby=nam

7、e&order=asc:指定返冋结果按照哪个属性排序，以及排序顺序。•?animal_type_id=l：指定筛选条件参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET/zoo/ID/animals与GET/animals?zoo_id=TD的含义是相同的。七、状态码（StatusCodes）服务器向用户返回的状态码和捉示信息，常见的冇以下一些（方括号屮是该状态码对应的HTTP动词）。•200OK-IGETJ：服务器成功返回用户请求的数据，该操作是幕等的（Idempotent）o

8、•201CREATED-[POST/PUT/PATCH]：用户新建或修改数据成功。•202Accepted-[*]：表示一个请求已经进入后台排队（异步任务）•204NOCONTENT-[DELETE]：用户删除数据成功。•400INVALIDREQUEST-[POST/PUT/PATCHJ：用八发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幕等的。•401Unauthorized-H：表示用户没有权限（令牌、用