API接口

API的初学

API 是一个一些软件组件之间进行交互的接口。
通过阅读一些文档，了解到API 的设计,主要是RESTful的设计规范。所谓RESTful API就是符合REST架构设计的API。

RESTful架构

RESTful架构，是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便，所以正得到越来越多网站的采用。
REST是Representational State Transfer的缩写，即"表现层状态转化"，而表现层，指的是“资源”的表现层（资源就是网络上的一个实体，或者说是网络上的一个具体信息。可以是一张图片，一段话等），每一个资源都可以用一个独一无二的URI指向它（这里也了解到URI和URL的不同， URI：统一资源标志符——Uniform Resource Identifier；URL：统一资源定位符——uniform resource location。两个都是定位资源的，但URL是URI的子集），通过访问每个URI就能访问到对应的“资源”。资源是实体，而我们要让他表现出来，表现出来的形式就叫做表现层。就有了我们各种的表现格式，例如txt，html等。
而客户端和服务端发生互动时，客户端需采取操作，来使服务端反应，常见的操作有GET、POST、PUT、DELETE。

URL的设计

RESTful 的核心思想就是，客户端发出的数据操作指令都是"动词 + 宾语"的结构。动词就是上边讲到的四种操作，一般大写。
但当有些客户端只能用GET和POST时，就需要把POST请求模拟其他两个请求，下边这个就是用PUT覆盖POST。

POST /api/Person/4 HTTP/1.1  
X-HTTP-Method-Override: PUT

说完动词，就是宾语，在URL中，宾语必须是名词，单复数没有太大关系，但用复数较好。
在有多级URL时

GET /authors/12/categories/1

就要避免这种情况，更好的做法是，除了第一级，其他级别都用查询字符串表达。

GET /authors/12?categories=1

状态码的返回

状态码一般包括下边五种，
1xx：相关信息
2xx：操作成功
3xx：重定向
4xx：客户端错误
5xx：服务器错误
接下来详细介绍下各个状态码：
1xx不太用
2xx：中，200状态码表示操作成功，但是不同的方法可以返回更精确的状态码；202 Accepted状态码表示服务器已经收到请求，但还未进行处理，会在未来再处理，通常用于异步操作。
3xx：主要是303 See Other，暂时重定向，常用于POST、PUT和DELETE请求。
4xx：400 Bad Request：服务器不理解客户端的请求，未做任何处理。404 Not Found表示所请求的资源不存在，或不可用。其他状态码等常用到时再进行说明。
5xx：状态码表示服务端错误。500 Internal Server Error表示客户端请求有效，服务器处理时发生了意外。503 Service Unavailable表示服务器无法处理请求，一般用于网站维护状态。

返回值

应注意API返回时应返回JOSN格式。
参考链接
http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html