4、构建 API 的全面指南-优快云博客

本文链接：https://blog.youkuaiyun.com/neovim7hacker/article/details/149706433

构建 API 的全面指南

1. 数据设计与 API 一致性

在许多组织中，主动调查数据设计和治理方面的需求非常有帮助。拥有一个通用的领域数据字典可以补充标准，为公司提供一致性的组织能够让消费者更好地理解和连接 API 响应。在某些领域，可能已经存在广泛使用的术语，应加以利用。

2. 集合与分页

对于 GET /attendees 请求，有两种响应模型：
- 原始数组响应 ：

GET http://mastering-api.com/attendees
---
200 OK
[
    {
        "displayName": "Jim",
        "givenName": "James",
        "surname": "Gough",
        "email": "jim@mastering-api.com",
        "id": 1
    },
    ...
]

嵌套对象响应 ：这种方式允许对更大的集合和分页进行建模。分页涉及返回部分结果，并提供消费者请求下一组结果的说明。如果后期添加分页并从数组转换为对象以添加 @nextLink，可能会破坏兼容性。

GET http://mastering-api.com/attendees
---
200 OK
{
    "value": [
        {
            "displayName": "Jim",
            "givenName