API 设计对比

api-design.org

API 设计对比

常见的 API 设计方式

随心所欲

HTTP 请求	优点	缺点	得分
GET /create/user?username={username}	不需要思考	罄竹难书	1
GET /list/user/by-page/{pageNo}
DEL /update/password

规范的 RPC

HTTP 请求	优点	缺点	得分
POST /createUser	直观	日志统计麻烦	3
GET /readUser		LB 不方便
POST /updateUser		过滤略繁琐
POST /deleteUser
GET /listUsers
GET /listPopularUsers
GET /searchUsers
POST /followUser
POST /unfollowUser

伪 RESTful

HTTP 请求	优点	缺点	得分
POST /users/create	m2m		4
GET /users/{userId}
POST /users/{userId}/update
POST /users/{userId}/delete
GET /users/
GET /users/popular
GET /users/search?q={q}
POST /users/{userId}/follow
POST /users/{userId}/unfollow

纯 RESTful

HTTP 请求	优点	缺点	得分
POST /users	满足强迫症	m2m	4
GET /users/{userId}
PUT /users/{userId}
DEL /users/{userId}
GET /users
GET /users/popular
GET /users/search
PUT /me/following/{userId}
DEL /me/following/{userId}

GraphQL

class Project {
    int id;
    String name;
    Creator Creator; // id, name
}

{
    Project(byid=20): Project
}

常用 API 设计参考

URL 表示资源

1. 要么最后一个单词是实体
2. 要么最后两个单词是 实体+修饰词（/posts/search, /me/followship/from-me, /me/followship/to-me)
3. 和当前用户相关的信息，放入单独的 object 中

分页设计

offset && limit 方式

/posts?offset=290&limit=20

/posts?page=3&per_page=20

• 简单易懂，和 SQL 直接映射
• 能选择指定页
• 频繁变化的数据，可能出现重复、遗漏的情况
• 数据量大时有性能问题

cursor 方式

/posts?cursor={cursor}

• 灵活，支持任意的分页方案
• 高性能 select * from posts where id < {postId}
• 不支持展示指定页的内容

relation 示例

{
    "post": {
        "id": 291029032,
        "title": "这是一篇极好的文章",
        "author": {
            "id": 923092,
            "username": "小明同学",
            "user_relation": {
                "is_blocked_by_me": true,
                "is_followed_by_me": true,
                "is_following_me": false
            }
        },
        "post_relation": {
            "is_editable": false,
            "is_subscribed": false
        }
    }
}

注册

RESTful

• POST /users/
• POST /users/phonenumber
• POST /users/wechat

类 RPC

• POST /auth/register
• POST /auth/register/phonenumber~
• POST /auth/register/wechat

登录

RESTful 后续可方便切换登录方式

• POST /tokens/
• POST /tokens/phonenumber
• POST /tokens/wechat

类 RPC

• POST /auth/login
• POST /auth/login/phonenumber
• POST /auth/login/wechat

文章列表

普通列表

• GET /posts/
• GET /posts/popular
• GET /posts/recent
• GET /posts/search?q={q}

按分类、标签过滤

• GET /categories/{cat}/posts
• GET /tags/{cat}/posts
• GET /posts/search?q={q}&cats={cat1,cat2}&tags={tag1,tag2} 高级查询

订阅文章

伪 RESTful

• POST /posts/{postId}/subscribe

纯 RESTful

• PUT /me/subscribing/{postId}
• PUT /me/subscribing-posts/{postId}

我的列表

返回实体

• GET /me/subscribing-posts 我的订阅
• GET /me/followers 我的关注
• GET /me/followees 我的粉丝

返回 relation（能显示更多的信息，如创建时间，类型等）

• GET /me/subscribing 我的订阅
• GET /me/followships/from-me 我的关注
• GET /me/followships/to-me 我的粉丝
• GET /me/followships/incoming 我的关注（请求）
• GET /me/followships/outgoing 我的粉丝（请求）
• GET /me/following 我的关注
• GET /me/followed 我的粉丝