什么是web API接口？
web API接口可以理解为一种约定，它规定了客户端如何与服务器进行交互。客户端通过特定的请求方式，向服务器发送包含必要参数的请求URL，服务器则会根据这些请求返回相应的数据。
请求方式主要包括：GET、POST、PUT、PATCH等，它们各自承担不同的功能。
请求参数通常以JSON或XML格式呈现，包含key-value类型的键值对。
响应结果同样以JSON或XML格式返回，也是key-value类型的键值对。
如何编写接口？
编写接口需要遵循一定的规则（规范），通过规范化的URL链接，并确定请求方式、请求数据以及响应结果。
接口规范：目前主流的web API接口规范是RESTful。
RESTful介绍
RESTful并非特指某项技术，而是一种软件架构风格。REST是Representational State Transfer的缩写，中文翻译为“表征状态转移”或“表现层状态转化”。
域名
为了清晰标识接口URL，通常在域名中使用”api”关键字。
例如：
https://api.example.com
https://example.org/api/
注：当看到URL中包含”api”字样时，通常意味着该链接用于完成前后台的数据交互。
版本
版本信息通常包含在URL中，以便区分不同版本的数据资源。
例如：
https://api.example.com/v1/
https://api.example.com/v2/
v1、v2等表示不同的数据版本，前提是同一资源存在多个版本。
此外，版本信息也可以放在请求头中。
URL路径
在RESTful API中，任何网络资源都应使用名词表示（通常为复数形式）。
例如：
https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees
URL中不应包含操作资源的动词，除非是特殊情况。
错误示范：
https://api.baidu.com/delete-user
特殊接口可以包含动词，因为这些接口通常没有明确的资源，或动词本身就是接口的核心含义。
例如：
https://api.baidu.com/place/search
https://api.baidu.com/login
method请求方式
GET：从服务器获取资源（一项或多项）
POST：在服务器创建新资源
PUT：在服务器更新资源（客户端提供完整资源）
PATCH：在服务器更新资源（客户端提供部分修改）
DELETE：从服务器删除资源
过滤
通过在URL中传递参数来实现搜索条件的过滤。
例如：
https://api.example.com/v1/zoos?limit=10：指定返回记录数量
https://api.example.com/v1/zoos?offset=10：指定返回记录的开始位置
https://api.example.com/v1/zoos?page=2&per_page=100：指定页码和每页记录数
https://api.example.com/v1/zoos?sortby=name&order=asc：指定排序属性和顺序
https://api.example.com/v1/zoos?animal_type_id=1：指定筛选条件
状态码
200 OK – [GET]：服务器成功返回请求的数据，该操作是幂等的。
201 CREATED – [POST/PUT/PATCH]：用户成功创建或修改数据。
202 Accepted – [*]：表示请求已进入后台处理（异步任务）。
204 NO CONTENT – [DELETE]：用户成功删除数据。
301：永久重定向
302：暂时重定向
400 INVALID REQUEST – [POST/PUT/PATCH]：用户请求有误，服务器未进行数据操作，该操作是幂等的。
401 Unauthorized – [*]：用户没有权限（令牌、用户名、密码错误）。
403 Forbidden – [*]：用户有权限，但访问被禁止。
404 NOT FOUND – [*]：用户请求的资源不存在，服务器未进行操作，该操作是幂等的。
406 Not Acceptable – [GET]：用户请求的格式不可得。
410 Gone -[GET]：用户请求的资源已被永久删除。
422 Unprocesable entity – [POST/PUT/PATCH]：创建对象时发生验证错误。
500 INTERNAL SERVER ERROR – [*]：服务器发生错误，用户无法判断请求是否成功。
错误处理
当状态码为4xx时，应返回错误信息，以”error”作为key。
{
error: “Invalid API key”
}
返回结果
服务器返回的结果应符合以下规范：
GET /collection：返回资源对象列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回空文档
{
“status”: 0,
“msg”: “ok”,
“results”:[
{
“name”:”肯德基(罗餐厅)”,
“location”:{
“lat”:31.415354,
“lng”:121.357339
},
“address”:”月罗路2380号”,
“province”:”上海市”,
“city”:”上海市”,
“area”:”宝山区”,
“street_id”:”339ed41ae1d6dc320a5cb37c”,
“telephone”:”(021)56761006″,
“detail”:1,
“uid”:”339ed41ae1d6dc320a5cb37c”
}
…
]
}
Hypermedia API
RESTful API最好能够实现Hypermedia，即在返回结果中提供链接，指向其他API方法，使用户无需查阅文档即可知道下一步操作。
{“link”: {
“rel”: “collection https://www.example.com/zoos”,
“href”: “https://api.example.com/zoos”,
“title”: “List of zoos”,
“type”: “application/vnd.yourformat+json”
}}