Golang学习：RESUful API最佳实践

Golang学习：RESUful API最佳实践

1、什么是API、URL？

API是程序应用编程接口，对外的server服务调用的接口，客户端通过调用不同的API可以得到相应的数据
URl是资源统一定位符，即我们输入www.baidu.com就是一个URL，资源可以是服务器上的图片，文档，视频、程序等都可以由一个资源统一标识符进行定位，每个URL代表一种资源

2、什么是RESUful API设计

RESUful API设计是最近WEB开发流行的一种设计规范，不是设计架构的标准，使用HTTP通讯协议，JSON作为通讯参数的数据格式，尽量避免使用XML作为数据格式

3、RESUful API特点

RESUful API有以下几个特点：

1. 统一接口，代码风格一致
2. 可缓存，读大于写的请求会放到缓存中
3. 分层，一个API分为多个服务，每个服务负责它其中的一部分

4、RESUful API设计原则

1. 以URL(统一资源定位符)风格设计API
2. 通过不同的METHOD(GET->SELECT,POST->INSTRT,PUT->UPDATE,DELETE->DELETE)来对应资源的CRUD（增查改删 ）
3. 返回码（Status Code）符合HTTP资源描述的规定

5、HTTP动词

GET(SELECT)：从服务器取出一个（多个）资源
POST(CREATE)：在服务器上新增一个资源
PUT(UPDATE)：在服务器上更新一个资源（客户端需要提供更新后的资源）
DELETE(DELETE)：从服务器上删除一个资源

6、数据进行过滤

如果数据量很大，但是客户端不需要所有数据的时候，API应该提供参数进行过滤数据，然后返回数据，如：

指定返回记录的数量，如limit = 10
指定返回记录的开始位置：offset = 10
指定第几页，以及每页的记录数，如：page = 1 and per_page = 20
指定返回结构按照哪个属性排序，以及排序的顺序，如：sortb = “id” and order = “desc”
指定过滤（筛选）的条件，如 id = 10001

7、状态码介绍

200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的
201 CREATED - [POST/PUT/PUTCH]：用户新建或修改数据成功
202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功，请求成功不返回任何数据
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改的操作，该操作是幂等的
401 Unauthorized - [*]：用户没有权限（令牌、用户名、密码错误）
403 Forbidden - [*]：用户得到了权限（与401错误相对），但是拒绝（禁止）访问
404 NOT FOUND - [*]：用户发出的请求不存在（请求错误），服务器没有进行操作，该操作是幂等的
405 Method Not Allowed [*]：禁止使用请求中指定的方法
406 Not Acceptable - [GET]：用户请求的格式不可得（如用户请求JSON格式，但是之后XML格式）
410 Gone - [GET]：用户请求的资源被永久删除，且不会再得到
422 Unprocesable entity - [POST/PUT/PATCH]：当创建一个对象时，发生一个验证错误
500 INTERANAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功

8、错误码介绍

当用户请求操作发生错误时，应该给用户返回错误信息，一般出错信息以error作为键，出错详情信息作为值，格式为JSON，如下：

error:{ "msg":"err", "status":200, "data":"用户名或密码错误" }

msg表示用户操作是否在正常，通常使用"ok"和"error"表示
status表示用户操作返回的HTTP状态码
data表示用户操作返回的错误/正确信息

9、RESUful API简单例子

1.创建用户

URL：/user Method：POST SC：201、400,、500（201表示新增成功，400表示客户端出现错误，服务器不进行新增操作，500表示服务器发生错误）

2.获取用户

URL：/user/id Method：GET SC：200、400、401、403、500（200表示请求成功，服务器成功返回用户请求数据，401表示用户没有得到授权令牌，403表示用户得到授权令牌但是访问是禁止的）

3.得到用户所有订单

URL：/user/id/orders Method：GET SC：200、400、401、403、500

4.删除用户某个订单

URL：/user/id/orders/id Method：DELETE SC：204、400、500（204表示用户删除数据成功，请求不返回任何数据）

10、身份验证

不是所有的API都是对外开放的，如果API不对外开放的话，需要进行验证和授权用户信息

验证：验证用户的身份，一般需要用户进行登陆，提供用户的账号密码等信息
授权：对用户请求特定的资源（API）需要设置相应的访问权限

通常情况下，如果用户没有进行验证，需要返回401错误码，用户验证成了，但是没有授权访问的权限，需要返回403错误码

11、编写文档

制定一份可读性很高的API文档，能够让使用者很清楚的知道API的作用（发送的参数、返回值等）

参考地址：
https://blog.csdn.net/liuqun0319/article/details/88050269
https://www.imooc.com/article/17587
http://www.ruanyifeng.com/blog/2014/05/restful_api.html
https://www.cnblogs.com/imyalost/p/7923230.html