API接口设计规范 RESETful (API接口设计)
本文目录导航：
RESETful API接口设计规范
开发环节中，咱们常需提供API接口给客户端或第三方经常使用，如何构建易于了解的API至关关键。
若在设计API时遵照规范，开发环节中的沟通老本和效率将大大优化。
本文将讨论RESTful API的设计规范。
以下为贯通全文的几个关键术语：资源（单个对象的实例，如生物）、汇合（同类型对象的汇合，如生物们）、HTTP（网络通讯协定）、消费者（可动员HTTP恳求的客户端运行程序）、第三方开发者（非名目组成员但宿愿经常使用数据的开发者）、服务（可经过网络访问的HTTP服务/运行）、节点（主机上的API URL，可代表资源或整个汇合）、幂等性（无反作用，可屡次执行）、URL段（URL中由斜杠分隔的信息段）。
数据形象与设计：需确定数据库设计及提供的web服务配置，以启动API设计。
API应尽或者形象业务逻辑和数据，以便经常使用者轻松上手。
恳求方法：经常出现的HTTP恳求方法有GET（检索资源）和POST（创立资源）。
以下为四个半关键的HTTP动词：GET（检索）、POST（创立）、PUT（降级整个资源）、PATCH（降级资源属性）、DELETE（删除资源）。
此外，还有HEAD（检索元数据）和OPTIONS（检索操作信息）。
RESTful API应应用这些恳求方法启动交互，且URL段中不蕴含任何举措。
版本管理：运行的外围和数据关联相关会始终变动，因此API版本管理至关关键。
修正API或者造成向后不兼容，影响经常使用者。
为确保运行开展并满足经常使用者需求，需在引入新版本的同时保障旧版本的反常访问。
API剖析：继续跟踪客户端经常使用的API版本和端点信息，如每次恳求自增计数器。
跟踪API有助于保障罕用API的有效性。
API Root URL：API根地址对开发者至关关键。
坚持根入口点便捷可提高开发者接受度。
依据运行规模，API可搁置于子域或根域名下，并蕴含相关内容。
端点：端点指向特定资源或资源汇合的URL。
针对每个端点，需列出有效的HTTP动词和端点组合。
过滤器：当客户端恳求对象列表时，前往合乎查问条件的一切对象列表。
过滤器可最小化网络传输并放慢查问结果失掉。
形态码：经常使用适合的HTTP形态码对RESTful API至关关键。
经常出现形态码包括200 OK、201 CREATED、204 NO CONTENT等。
形态码范畴：1xx范畴形态码用于底层HTTP配置，2xx范畴形态码用于成功信息，3xx范畴形态码用于重定向，4xx范畴形态码用于客户端失误，5xx范畴形态码用于主机端失误。
预期前往文档：经常使用不同的HTTP动词执执行作时，消费者须要在前往中失掉某些信息。
典型的RESTful API包括GET、POST、PUT、PATCH、DELETE等操作。
认证：主机需确定启动恳求的用户身份。
OAuth2.0等认证方法可确保客户端安保访问API。
Content Type：大少数API提供JSON数据允许。
前往有效的数据格局可让开发者经常使用盛行的言语和框架启动解析。
超媒体API：超媒体API或者是RESTful API设计的未来。
它经过恳求API根失掉URL列表，每个URL都指向一个汇合，并形容客户端可了解的信息。
文档：API文档对开发者至关关键。
文档应面向一切开发者，确保易于了解，并提供完整的示例恳求和照应主体。
修订：原始的HTTP封装：HTTP恳求和照应都由键值对集组成，包括头部、恳求体、照应体等。
经常使用工具检查原始HTTP封装对API设计至关关键。
Restful接口文档规范
基于目前的大前端时代，关于终年担任后盾开发的我来说， 最关键的就是提供稳固的接口和文档。
便于小同伴们启动业务对接。
当下罕用的是RestFul格调的定义规范， 之前开发是清一色Get、Post。
引入RestFul后觉得接口定义规范很多，看接口地址就通晓是什么配置， 一同来看看列的一些基础规范吧。
API与客户端用户的通讯协定，总是经常使用HTTPS协定，以确保交互数据的传输安保。
应该尽量将API部署在公用域名之下：假设确定API很便捷,不会有进一步裁减,可以思考放在主域名下：https:///v {n} 1、应该将API的版本号放入URL。
2、驳回多版本并存，增量颁布的模式。
3、n代表版本号，分为整型和浮点型 整型： 大配置版本， 如v1、v2、v3 ... 浮点型： 补充配置版本， 如v1.1、v1.2、v2.1、v2.2 ... 4、关于一个 API 或服务，应在消费中最多保管 3 个最详细的版本 门路又称终点（end point），示意API的详细网址。
1、在RESTful架构中，每个网址代表一种资源(resource),所以网址中不能有动词，只能有名词。
【所用的名词往往与数据库的表格名对应】 2、数据库中的表普通都是同种记载的汇合(collection),所以API中的名词也应该经常使用双数。
例子:https:///v1/usersGET（SELECT）： 从主机取出资源（一项或多项）。
POST（CREATE）： 在主机新建一个资源。
PUT（UPDATE）： 在主机降级资源（客户端提供扭转后的完整资源）。
DELETE（DELETE）： 从主机删除资源。
例子： GET /v1/products 失掉一切商品 GET /v1/products/ID 失掉某个指定商品的信息 POST /v1/products 新建一个商品 PUT /v1/products/ID 降级某个指定商品的信息 DELETE /v1/products/ID 删除某个商品,更正当的设计详见【9、非RESTful API的需求】 GET /v1/products/ID/purchases 列出某个指定商品的一切投资者 GET /v1/products/ID/purchases/ID 失掉某个指定商品的指定投资者信息 若记载数量很多，主机无法能前往所有记载给用户。
API应该提供分页参数及其它挑选参数，过滤前往结果。
/v1/products?page=1&pageSize=20 指定第几页，以及每页的记载数。
/v1/products?sortBy=name&order=asc 指定前往结果依照哪个属性排序，以及排序顺序。
传入参数分为4种类型： 1、cookie： 普通用于OAuth认证 2、request header： 普通用于OAuth认证 3、恳求body数据： 4、地址栏参数： 1）restful 地址栏参数 /v1/products/ID ID为产品编号，失掉产品编号为ID的信息 2）get模式的查问字段 见【六、过滤信息】 response： ---------------------------------------- { status: 200, // 详见【status】>Restful API 接口设计规范以及规范
了解RESTful概念，咱们首先要知道REST代表的是Representational State Transfer，这是构建架构的一组规定和解放。
REST并不是发明新的技术或组件，而是应用Web的现有特色和才干，更好地利用Web规范中的一些准绳和解放。
实践上，REST架构格调并不是绑定在HTTP上，但目前HTTP是惟一与REST相关的实例。
因此，咱们将经过HTTP成功REST。
RESTful架构的外围思念在于经常使用一致资源标识符（URI）来示意资源，规范HTTP方法（如GET、POST、PUT、DELETE、Patch）来操作资源。
资源表述是指以机器可读的模式形容资源形态的文档。
资源与URI毫不相关，任何足够关键且被援用的事物都可以是资源，每个资源领有一个世界惟一的URL。
例如，石榴、数据库中的一条记载等都是资源。
当客户端恳求资源时，主机将提供一个蕴含资源信息的文档作为照应，这就是资源的表述。
资源可以有多种表述，以顺应不同的需求，如全体概括性表述、详细表述或不同格局（如JSON、XML）表述。
资源之间经过链接启动衔接，这不只是成功从一个资源到另一个资源的导航，也是资源形态转移的基础。
例如，在GitHub恳求某个组织下的名目列表时，照应头和照应体中蕴含链接，指点客户端访问更多资源。
客户端与主机之间的互动触及数据和形态的变动，HTTP协定作为有形态协定，一切形态都保管在主机端。
因此，客户端操作主机必定经过特定手腕让主机出现形态转化，这一环节称为体现层形态转移。
客户端可以经常使用HTTP协定的四个基本动词（GET、POST、PUT、DELETE）来执行操作，如失掉资源、创立资源、降级资源或删除资源。
在设计RESTful架构时，应器重资源表述的链接提供，以增强资源的连通性，而不只仅专一于CRUD操作。
同时，了解形态转移的概念关于构建照应式和灵活的Web运行至关关键。
phper