如何设计API

·  阅读 104

在一个项目中,我见过所有接口设计,几乎全部是使用POST方法,看接口规范,果然是设计如此。要是说,所有接口都使用POST方法,又不是不能工作,当然能,有问题吗,当然有,最大的问题是,没有遵循规范,而遵循规范可以使我们降低沟通成本。

一个好的通用的接口,是需要遵循一些原则的:

1、面向资源设计

资源是被命名的实体,面向资源的API会被构建成资源层次结构,在这个结构中,一个资源节点下可能会有多个子资源,又或者由相同类型的资源组合而成的集合资源列表,

一个集合包含相同类型的资源列表。 例如,一个用户拥有一组联系人。 资源具有一些状态和零个或多个子资源。 每个子资源可以是一个简单资源或一个集合资源。

如用户资源,users,那么可能会有的资源是

用户信息:users/messages/* 用户标签:users/labels/* 用户资料:users/profile/*

每个资源必须有一个唯一的名称,名称的组成如下:

资源自身的 ID、任何父资源的 ID 及其 API 服务名称。集合是一种特殊资源类型,如目录是文件资源的集合。

//library.googleapis.com / shelves / shelf1 / books / book2 API服务名称 / 集合ID / 资源ID / 集合ID / 资源ID

资源ID:资源名称中非末尾的资源ID名称之后一个URI段,比如shelf1只能是 / shelf1 /,而不能出现 / shelf1 / shelf / parse / books 这样,但是在末尾是可以有多个URI段,如 / book2 / java / jdk1-8.java

集合ID:复数形式的小写驼峰体,如books

2、方法

业务逻辑的CRUD,对应的方法则有GET、POST、PUT、DELETE

GET方法:需要一个资源名称和零个或多个参数作为输入,并返回自定资源,GET方法的接口是幂等的

POST方法:需要一个父资源名称、一个资源以及零个或多个参数作为输入,是在指定资源下创建资源,所以POST方法的接口不是幂等的

PUT方法:需要一条包含一个资源的请求消息和零个或多个参数作为输入,更新指定的资源,如果资源不存在,那么可以创建资源,PUT方法的接口是幂等

DELETE方法:需要一个资源名称和零个或多个参数作为输入,删除指定资源,DELETE方法的接口是幂等的

还有其他的方法,如下图:

3、错误码

谷歌API错误code.proto,定义了自己的一套错误码模型,每一个错误码都有描述对应http状态码的含义,这里我想说,其实直接使用http状态码会更清晰,因为对http状态码大家都熟悉,一看就知道其代表的含义,没必要又增加一层翻译的沟通成本,常见的有:

HTTPgRPC说明
200OK无错误。
400INVALID_ARGUMENT客户端指定了无效参数。如需了解详情,请查看错误消息和错误详细信息。
400FAILED_PRECONDITION请求无法在当前系统状态下执行,例如删除非空目录。
400OUT_OF_RANGE客户端指定了无效范围。
401UNAUTHENTICATED由于 OAuth 令牌丢失、无效或过期,请求未通过身份验证。
403PERMISSION_DENIED客户端权限不足。这可能是因为 OAuth 令牌没有正确的范围、客户端没有权限或者 API 尚未启用。
404NOT_FOUND未找到指定的资源。
409ABORTED并发冲突,例如读取/修改/写入冲突。
409ALREADY_EXISTS客户端尝试创建的资源已存在。
429RESOURCE_EXHAUSTED资源配额不足或达到速率限制。如需了解详情,客户端应该查找 google.rpc.QuotaFailure 错误详细信息。
499CANCELLED请求被客户端取消。
500DATA_LOSS出现不可恢复的数据丢失或数据损坏。客户端应该向用户报告错误。
500UNKNOWN出现未知的服务器错误。通常是服务器错误。
500INTERNAL出现内部服务器错误。通常是服务器错误。
501NOT_IMPLEMENTED API方法未通过服务器实现。
502不适用到达服务器前发生网络错误。通常是网络中断或配置错误。
503UNAVAILABLE服务不可用。通常是服务器已关闭。
504DEADLINE_EXCEEDED超出请求时限。仅当调用者设置的时限比方法的默认时限短(即请求的时限不足以让服务器处理请求)并且请求未在时限范围内完成时,才会发生这种情况。

参考:

cloud.google.com/apis/design

www.rfc-editor.org/rfc/rfc7231…

分类:
后端
标签:
收藏成功!
已添加到「」, 点击更改