restful接口设计规范总结 (restful)
本文目录导航：
restful接口设计规范总结
Resource（资源）：对象的单个实例，如生物、文本、图片等。
每个资源都有一个URI（一致资源定位符）作为惟一标识。
汇合是多个对象的组合，如生物汇合。
第三方支经常使用接口的开发者。
体现层是资源的多种出现方式，如文本的txt、HTML、XML、JSON格局，图片的JPG、PNG格局。
形态转化是客户端与主机互动环节中数据和形态的变动，经过HTTP协定成功，客户端关键经常使用GET、POST、PUT、DELETE四个动词。
URI仅标识资源位置，不示意方式，后缀名如属于体现层，应经过HTTP恳求头中的Accept和Content-Type字段形容体现层。
RESTful架构总结：每个URI代表一种资源，客户端与主机间传递资源体现层，客户端经过HTTP动词操作主机资源。
REST接口规范：GET用于检索资源或资源列表，POST用于创立资源，PUT用于降级资源（提供整个资源），PATCH用于降级资源（提供局部消息），DELETE用于删除资源。
门路设计应经常使用名词示意API详细网址，与数据库表名对应，通经常常使用双数方式示意汇合，如：/zoos（一切生物园）/zoos/ID（指定生物园消息）/zoos/ID/animals（指定生物园一切生物）。
版本管理：API版本号放入URL，如，或经过HTTP头消息，但URL方式更直观。
过滤消息：API提供参数以过滤前往结果，如limit、offset、sortby等。
形态码：1xx消息，2xx成功，3xx重定向，4xx客户端失误，5xx主机失误。
经常出现形态码及含意包括：200 OK、201 CREATED、202 Accepted、204 NO CONTENT、400 INVALID REQUEST、401 Unauthorized等。
失误会决：4xx形态码时应前往出错消息，键值对方式如{ error: Invalid API key }。
前往结果应合乎操作规范，如GET /collection前往资源列表，POST /collection前往重生成资源等。
Hypermedia API：前往结果中蕴含链接指向其余API方法，成功无需文档即可了解操作流程，设计准则为HATEOAS（Hypermedia as the Engine of Application state）。
如GitHub API设计，经过链接指援用户调用不同API方法。
什么是RestFul格调
Restful格调，一种基于HTTP协定的软件架构设计，公用于构建网络运行的API。
此格调将数据与配置视为资源，并经常使用惟一URL标识资源。
客户端应用GET、POST、PUT、DELETE等HTTP方法对资源口头操作。
主机依据恳求方法及URL口头操作并前往资源示意。
其设计准则蕴含：1. 明白、易懂且易用的接口，优化了系统可裁减性和灵敏性。
现代Web服务中盛行驳回此设计思维。
举例说明，经常使用SpringMVC注解定义RESTful API，GET、POST、PUT、DELETE对应资源失掉、创立、降级、删除操作。
经过@RequestMapping指定URL门路，@PathVariable和@RequestBody失掉恳求参数。
以此，经过URL与HTTP方法操作产品资源，成功RESTful格调的API设计。
该格调的API设计确保了接口明晰、易于了解和经常使用，同时增强了系统的可伸缩性和灵敏性。
它是构建现代Web服务的抢手理念。
RESTful API 最佳通常总结
RESTful 是目前盛行的 API 设计规范，用于 Web 数据接口设计。
它的外围现实是客户端经过 动词 + 宾语 的结构发送数据操作指令，如 GET /articles 示意失掉一切文章，其中 GET 是动词，/articles 是宾语，对应 HTTP 方法如 GET、POST、PUT、PATCH、DELETE，HTTP 方法一概大写。
针对客户端仅能经常使用 GET 和 POST 的状况，主机需接受 POST 方法模拟其余三个方法，如 PUT、PATCH、DELETE。
此时，客户端需在 HTTP 恳求中减少 X-HTTP-Method-Override 属性，批示主机经常使用哪个动词。
同时，宾语必定为名词，防止经常使用动词，且 API URL 通经常常使用双数方式以坚持分歧性。
为防止复杂且难以裁减的多级 URL 设计，介绍经常使用查问字符串表白除第一级外的其余分类级别。
例如，失掉已颁布的文章，经常使用 GET /articles?status=published，而不是 GET /articles/author/some/ published。
这种设计更易于了解且便于裁减。
HTTP 形态码是 API 回应的关键组成局部，批示客户端操作的口头状况。
形态码分为五个类别，包括 1xx、2xx、3xx、4xx 和 5xx。
2xx 示意操作成功，如 POST 操作成功前往 201 Created，DELETE 操作成功前往 204 No Content。
3xx 形态码如 303 See Other 示意经常使用另一个 URL。
4xx 形态码用于客户端失误，5xx 形态码用于服务端失误。
在 API 前往数据时，应经常使用 JSON 格局，而非纯文本，主机回应的 HTTP 头应设为 Content-Type: application/json，客户端恳求时应设 ACCEPT: application/json。
出现失误时，形态码应准确反映失误类型，而将详细失误消息蕴含在数据体中前往，防止前往 200 形态码覆盖失误。
为繁难用户操作，API 应提供关系链接，遵照 HATEOAS（Hypermedia As The Engine Of Application State）准则，准许用户依据链接发现更多操作。
以上是 RESTful API 设计的关键通常，旨在构建易于了解和经常使用的 API，提高 API 的可保养性和裁减性。
phper