如何设计一个良好的API接口？ _API接口

API是软件系统的核心，而我们在设计API接口的时候会面临着非常多的挑战：

场景上来看，它是多样的，如何设计一个随处适用的API？
我们所参与的业务不断演进的，如何设计一个有兼容性的API？
我们的软件流程是协同开发的，那我们如何实现对API的统一认知？

【如何设计一个良好的API接口？】今天我想和大家探讨一下如何设计一个良好的API接口，我觉得好的API设计需要同时考虑到这几个要素：标准化、兼容性、抽象性、简单性、高性能，可以说这几个要素缺一不可。

文章插图

标准化对于Web API标准化而言，一个非常好的案例就是Restful API 。目前业界的Open API多数是基于Restful API规范设计的。
1、等级模型需要注意的是Restful API它具有成熟度的模型。

其中Level 0是普通的请求响应模式。
Level 1引入了资源的概念，各个资源可以单独创建URI，与Level 0相比，它通过资源分而治之的方法来处理复杂问题。
Level 2引入了一套标准的HTTP协议，它通过遵守HTTP协议定义的动词并配合HTTP响应状态码来规范化Web API的标准。
Level 3中，使用超媒体可以使协议拥有自我描述的能力。

通常情况下，成熟度模型中达到Level 2就已经非常好了。

文章插图

2、URI在Restful API中，每一个URI代表着一种资源，是每一个资源的唯一定位符。所谓资源，它可以是服务器上的一段文本、一个文件、一张图片、一首歌曲，或者是一种服务。

文章插图

Restful API呢，规定了通过get/post/put/patch/delete等方式对服务端的资源进行操作。
因此，我们在定义一个Web API的时候，需要明确定义出它的请求方式、版本、资源名称和资源ID 。

文章插图

举个例子，要查看用户编码是101的用户信息，我可以定义get的请求方式，而他的版本是V1，资源名称是users，资源ID是1001 。

文章插图

这里可以思考一下，如果存在多个资源组合的情况呢？
事实上还可引入子资源的概念，需要明确定义出它的请求方式、版本、资源名称与资源ID，以及子资源名称与此资源ID 。

文章插图

举个例子，要查看用户编码是101的用户的权限信息，我可以定义get的请求方式。而他的版本是V1，主资源名称是Users，主资源ID是1001子资源名称是Roles，资源ID是101 。

文章插图

有时候，当一个自然变化难以使用标准的Restful API来命名时，就可以考虑使用一些特殊的actions命名。
比如密码修改接口，我可以定义Put的请求方式，而他的版本是V，主资源名称是users，主资源ID是101资源字段是password 。然后定义一个action的操作是modify 。

文章插图

3、错误码和返回机制与此同时啊，建议不要试图创建自己的错误码和返回错误机制。
很多时候呢，我们觉得提供更多的自定义的错误码有助于传递信息，但其实，如果只是传递信息的话，错误信息字段可以达到同样的效果。
此外，对于客户端来说，很难关注到那么多错误的细节，这样的设计只会让API的处理变得更加复杂，难于理解。
因此，我的建议是遵守Restful API的规范，使用HTTP规范的错误码。例如，我们用200表示请求成功，用400表示错误的请求，而500则表示服务器内部的错误。