最佳通常总结 RESTful API (最好的总结)
本文目录导航：
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 的可保养性和裁减性。
如何更好的设计RESTful API
一个好的RESTful API，应该具有以下特色：这个API应该是对阅读器友好的，能够很好地融入Web，而不是与Web貌合神离。
1.阅读器是最经常出现和最通用的REST客户端。
好的RESTful API应该能够经常使用阅读器+HTML成功一切的测试（不须要经常使用编程言语）。
这样的API还可以很繁难地经常使用各种智能化的Web配置测试、性能测试工具来做测试。
Web前端运行（基于阅读器的RIA运行、移动App等等）也可以很繁难地将多个RESTful API的配置组合起来，建造Mashup类的运行。
这个API中所蕴含的资源和关于资源的操作，应该是直观和容易了解的，并且合乎HTTP协定的要求。
REST开发又被称作“面向资源的开发”，这说明关于资源的形象，是设计RESTful API的外围内容。
RESTful API建模的环节与面向对象建模相似，是以名词为外围的。
这些名词就是资源，任何可命名的形象概念都可以定义为一个资源。
而HTTP协定并不是一种传输协定，它实践提供了一个操作资源的一致接口。
关于资源的任何操作，都应该映射到HTTP的几个有限的方法（罕用的有GET/POST/PUT/DELETE四个方法，还有不罕用的PATCH/HEAD/OPTIONS方法）下面。
所以RESTful API建模的环节，可以看作是具有一致接口解放的面向对象建模环节。
依照HTTP协定的规则，GET方法是安保且幂等的，POST方法是既不安保也不幂等的（可以用来作为一切写操作的通配方法），PUT、DELETE方法都是不安保但幂等的。
将对资源的操作正当映射到这四个方法下面，既不适度经常使用某个方法（例如适度经常使用GET方法或POST方法），也不减少过多的操作以致于HTTP的四个方法不够用。
2.假设发现资源上的操作过多，以致于HTTP的方法不够用，应该思考设计出更多的资源。
设计出更多资源（以及相应的URI）关于RESTful API来说并没有什么坏处。
这个API应该是松耦合的。
RESTful API的设计包括了三个墨守成规、由低到高的档次：资源形象、一致接口、超文本驱动。
正是这三个档次确保了RESTful API的松耦合性。
3.当设计面向互联网的API时，松耦合变成了一种“必定有”的强需求。
紧耦合的API十分软弱，一旦发布进来，主机端和客户端都不可继续退化。
尤其是主机端，发布进来的接口基本不敢改，改了之后，简直一切客户端运行立刻不可反常上班。
REST这种架构格调就是紧耦合API的解毒剂，这个话题可以谈的很深，这里就不倒退了。
感兴味的读者可以参考《REST实战》。
这个API中所经常使用的表述格局应该是经常出现的通用格局在RESTful API中，关于资源的操作，是经过在主机端-客户端之间传递资源的表述来直接成功的。
资源的表述可以有很多种格局，并且在照应和恳求中的资源表述格局也会有所不同。
GET/POST照应中的资源表述格局，经常出现的有HTML、XML、JSON；POST/PUT恳求中的资源表述格局，经常出现的有规范的HTML表单参数、XML、JSON。
4.这些经常出现表述格局，解决起来十分容易，有少量的框架和库提供支持。
所以除非有很正当的要求，通常不须要经常使用自定义的私有格局。
经常使用HTTP照应形态代码来表白各种出错状况HTTP照应形态代码，是HTTP协定这个一致接口中用来表白出错状况的规范机制。
照应形态代码分红两局部：status code和reason phase。
两局部都是可定制的，也可以经常使用规范的status code，只定制reason phase。
5.假设一个所谓的“RESTful API”关于任何恳求都前往200 OK照应，在照应的信息体中前往出错状况信息，这种做法显然不合乎“确保操作语义的可见性”这个REST架构格调的基本要求。
这个API应该关于HTTP缓存是友好的6.充沛应用好HTTP缓存是RESTful API可伸缩性的基本。
HTTP协定是一个分层的架构，从两端的user agent到origin server之间，可以拔出很多两边组件。
而在整个HTTP通讯链条的很多位置，都可以设置缓存。
HTTP协定内建有很好的缓存机制，可以分红过时模型和验证模型两套缓存机制。
假设API设计者齐全没有思考过如何应用HTTP缓存，那么这个API的可伸缩性会有很多疑问。
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