原文链接：Web API design best practices - Azure Architecture Center | Microsoft Docs当初网络上曾经有了很多服务商的公开API，能够让各类客户端调用，那么怎么才是一个设计低劣的web API呢？一般来讲应该具备以下规范：
平台无关性：应用API的能够是任何客户端，它们不必关怀API是怎么实现的。这就要求了交互时应用到的协定要标准化，并且要存在一种机制，能确保客户端和服务提供方在数据格式上达成统一。服务演变: web API能够自行更新迭代本人的性能，应用它的客户端不必做出任何批改就能持续应用这些API。服务端提供的所有性能要具备可发现性，使得客户端能充沛应用到它们。上面来说说设计web API时要思考的一些关键问题。
什么是REST？在2000年，Roy Fielding提出应用表述性状态转移（Representational State Transfer ，简称REST）来设计网络服务的构建办法。REST是一种基于超媒体来构建分布式系统的架构格调，它不应关注底层服务如何，也不必跟HTTP绑定，不过大部分REST API的实现还是基于了HTTP协定。让咱们先关注下如何应用HTTP来设计REST API接口。
在HTTP上应用REST的益处是它是一个有公开规范的协定，不须要这些API的提供方或应用方依赖任何特定实现计划，服务方和应用方能够用任意语言、工具包来提供REST服务实现，或创立HTTP申请以及解析HTTP响应报文。
基于HTTP设计RESTful API的次要准则有：
REST API的外围是资源，能够是客户能拜访到的任意物体、数据或服务每种资源都要有一个举世无双的URI来作为惟一标识符定位到该资源。比方一种客户订单能够这样形容：
https://adventure-works.com/orders/1客户通过替换资源表述来与服务交互。许多web API应用JSON作为数据转换格局。例如，一个针对下面URI的GET申请可能失去如下内容：
{"orderId":1,"orderValue":99.90,"productId":1,"quantity":1}REST API应用一套对立的接口，来帮忙解耦调用端和服务实现。在HTTP上构建REST API时，对立接口应用规范的HTTP动词来执行资源的操作，常常应用到的操作有GET,POST,PUT,PATCH和DELETE。REST API是无状态的。因为收回的HTTP申请是独立且无序的，因而没方法在申请间放弃这种长期会话状态。能存储信息的中央只能是API资源本身，而每个申请该当是原子操作。这样的束缚要求客户和特定服务器间不能保留任何关联，从而使得服务具备了高度的可伸缩性。任意的服务器能够解决任何的客户申请。然而，其余因素可能会限度这种可伸缩性，比方很多服务都要写数据到后端存储中，而这种繁多存储就很难扩大。对于这种数据存储该如何扩大的策略办法，能够参考Horizontal, vertical, and functional data partitioning.REST API的重要驱动外围是其表述内容中蕴含的超媒体链接。举个例子，上面展现了一个蕴含订单信息的JSON格局内容，它蕴含了一些链接，用来取得或更新与该订单关联的客户数据。
{ "orderID":3, "productID":2, "quantity":4, "orderValue":16.60, "links": [ {"rel":"product","href":"https://adventure-works.com/customers/3", "action":"GET" }, {"rel":"product","href":"https://adventure-works.com/customers/3", "action":"PUT" } ]}在2008年，Leonard Richardson提出了一个web API成熟度模型：
Level 0：仅有一个URI，用来解决所有POST申请 .Level 1：不同的资源提供独自的URI申请门路.Level 2：应用HTTP的method来定义在资源上的不同操作.Level 3：应用了超媒体（HATEOS，上面会提到）
围绕资源设计APIweb API须要裸露一些业务实体， 拿电商零碎来举例，次要的实体基本上就是客户和订单了。能够发送一个蕴含了订单信息的HTTP POST申请来创立一个订单，而响应报文该当告知这个订单是否创立胜利。请记得，提供进去的这些资源操作URI应尽量应用名词（资源名）来形容，而非动词（操作动作）。
https://adventure-works.com/orders // Goodhttps://adventure-works.com/create-order // Avoid一个所谓的资源不肯定要是一个实在的物理实体，比方对于订单来说，它可能在外部实现上用到了数张关系型数据库中的表，然而对于客户而言，它就是一个独自的实体。不要创立一些仅仅是把数据库对象做了个简略镜像展现的API。REST的指标是形容实体和可在其上执行的操作，而客户不应接触到外部实现。
...