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）的信息，还包括各种生物和雇员的信息，则它的门路应该设计成上方这样。
api接口的操作形式包括哪些
API接口的操作形式关键包括RESTful、GraphQL、gRPC、WebSocket和Webhook等几种。
首先，RESTful是一种基于资源和HTTP协定的设计格调。
它经过经常使用一致资源标识符作为资源的惟一标识，以及规范的HTTP动词来口头操作。
这种形式具有良好的可读性和易于缓存的特点，十分适宜构建合乎REST准则的轻量级和繁难的API。
例如，一个电商网站或者会提供RESTful API，准许开发者经过HTTP恳求失掉商品信息、下单或查问订单形态。
其次，GraphQL是一种用于API的查问言语和运转时的两边件。
与RESTful不同，GraphQL准许客户端按需失掉所需的数据，缩小不用要的数据传输。
它经常使用弱小的类型系统来定义数据模型和查问言语，使得客户端能够灵敏地组合和失掉所需的数据。
这关于移动运行、复杂数据相关和多端点的API恳求十分有用。
例如，一个社交媒体平台或者会经常使用GraphQL API，以便用户可以依据须要失掉其关注者的灵活、评论或点赞信息。
再者，gRPC是一个高性能、开源的远程环节调用框架，由Google开发并支持多种编程言语。
它经常使用Protocol Buffers作为接口定义言语，并提供极速、高效的跨言语交互。
gRPC实用于构建可裁减的服务和散布式系统，具有良好的性能、弱小的类型推断和智能生成的才干。
例如，在微服务架构中，不同的服务之间可以经过gRPC启动通讯，成功高效的数据替换和配置调用。
此外，WebSocket是一种在客户端和主机之间启动全双工通讯的协定。
它准许实时、双向的数据传输，实用于实时聊天、实时数据展现和单干运行等场景。
WebSocket经过建设耐久的衔接，可以实事实时的事情和信息替换。
例如，一个在线单干工具或者会经常使用WebSocket API，以便多个用户可以同时编辑文档、共享屏幕或启动语音通话。
最后，Webhook是一种回调机制，经过HTTP回调将运行程序的事情通知推送给客户端。
它准许构建实时势情驱动的运行程序，经常使用繁难的HTTP POST恳求启动通讯。
Webhook实用于运行程序集成和异步通知场景。
例如，一个名目治理工具或者会提供Webhook API，以便在名目形态降级或义务成功时智能发送通知给相关的用户或系统。
综上所述，API接口的操作形式包括RESTful、GraphQL、gRPC、WebSocket和Webhook等几种，每种形式都有其共同的特点和实用场景。
开发者可以依据实践需求选用最适宜的形式来构建高效、可裁减和安保的API接口。
RESTful 接口成功扼要指南
在前后端分别的Web运行架构中，REST是一种盛行的前后端交互方式的商定。
REST并不导致某个技术规范，后端开发者在成功中有着齐全的自主权，一些宣称RESTful的接口或者并未真正遵照其规范。
GitHub是一个让人惊叹的RESTful接口成功范例，其接口文档让人深入感遭到REST接口的美妙，合乎“接口的方式美感”的等候。
本文聚焦几个关键点，论述构建一个让前端开发者感到温馨的RESTful接口应该具有的个性。
REST简介
REST（REpresentational State Transfer）是一个术语缩写，直译为“表征形态转移”。
先不急于了解这个拗口的词，先看其实施细节。
REST是一种格调商定，其描画词方式为RESTful。
遵照REST格调的接口称为RESTful接口。
REST对恳求的商定
REST用于规范运行如何在HTTP层与API提供方启动数据交互。
以后阶段，GET和POST恳求或者已是你所相熟的HTTP方法，甚至你的整个运行或者齐全依赖这两种方法。
这无疑糜费了HTTP协定的后劲，而REST则充沛应用HTTP规范中的方法，成功接口描画的语义化。
REST架构商定在恳求层面两个关键方面：HTTP恳求的方法和恳求的链接。
API的URL
URL用于定位资源，与操作行为区离开来，象征着URL不应蕴含任何动词。
在REST架构中，URL应明白指向资源，而不应描画操作行为。
例如，不应在URL中产生“get”、“create”、“search”等动词。
这与术语定义“一致资源定位符”相分歧，标明URL用于定位资源，而非描画操作。
系统中简直只经常使用GET和POST方法成功一切接口操作，相似于仅经常使用DIV启动规划。
实践上，咱们有更多HTTP方法可用，包括GET、POST、PUT、PATCH、DELETE。
这些方法与数据的CRUD操作对应。
GET用于资源的读取。
CreatedPOST用于资源的创立。
Update
PUT和PATCH用于资源的降级。
PUT降级资源的所有信息，PATCH仅降级指定字段。
DELETE用于资源的删除。
分页、过滤
REST格调的接口或者示意单个资源或资源汇合。
访问资源汇合时，设计良好的接口应接受参数，准许只前往满足特定条件的资源列表。
这包括支持分页、搜查关键词、排序和依据字段过滤。
总结
本文从恳求角度选用几个关键点论述成功RESTful接口的基本要求。
遵照REST规范，可语义化描画HTTP恳求操作。
相熟REST格调接口后，可基本了解如何经常使用接口启动CRUD操作。
深化了解REST规范，可参考相关仓库。
phper