api接口规范 restful (api接口规范)
本文目录导航：
restful api接口规范
restful api接口规范如下：
1、协定
API与用户的通讯协定，总是经常使用HTTPs协定。
2、域名
应该尽量将API部署在公用域名之下。
假设确定API很繁难，不会有进一步裁减，可以思考放在主域名下。
3、版本（Versioning）
应该将API的版本号放入URL。
另一种做法是，将版本号放在HTTP头信息中，但不如放入URL繁难和直观。
Github驳回这种做法。
4、门路（Endpoint）
门路又称终点（endpoint），示意API的详细网址。
在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。
普通来说，数据库中的表都是同种记载的汇合（collection），所以API中的名词也应该经常使用双数。
举例来说，有一个API提供生物园（zoo）的信息，还包括各种生物和雇员的信息，则它的门路应该设计成上方这样。
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运行至关关键。
RESTful API定义及经常使用规范
RESTful设计格调是一种接口开发的指点思维而非详细规范，本文旨在为遵照该格调的HTTP RESTful API提供成功的最佳通常指南。
接口设计应遵照繁复、明晰的准绳，以HTTP方法（GET、POST、PUT、DELETE）定义操作，经过URL结构表现资源的档次相关。
在详细成功RESTful API时，设计者需留意以下几点： 1. **接口组织**：模块化治理接口，确保每个模块有明白的职责和版本控制。
API模块信息应存储在APP性能项中，经过初始化API模块接口失掉每个模块的endpoint和版本号。
2. **公共参数**：定义公共恳求参数并以Header方式传递，例如session id、user_id、token等。
这些参数在恳求中智能失掉，简化开发。
3. **安保性**：前往形态码来批示接口恳求的成功或失败，经常使用JSON格局的信息体提供失误码code和失误说明message。
同时，成功速率限度（Rate Limiting）战略以防止API滥用。
4. **恳求方法**：GET用于失掉资源、PUT用于降级资源、DELETE用于删除资源，POST则用于创立资源。
这些方法应基于幂等性准绳来选择经常使用GET、PUT或POST。
5. **参数解决**：确保从客户端失掉的json数据中数值类型字段以数值方式解决，不论其能否携带引号。
6. **工具允许**：介绍经常使用Postman作为接口测试工具，繁难启动接口测试与文档生成。
遵照上述指点，开发者能够构建高效、安保且易于保养的HTTP RESTful API，为服务提供稳固、照应迅速的接口允许。
phper