文档介绍：RESTfulAPI设计原则与规范一、背景与基础概念 2二、RESTfulAPI应遵循得原则 31、协议(Protocol) 32、域名(ROOTURL) 33、版本(Versioning) 34、路径(Endpoints) 35、HTTP动词(HTTPVerbs) 46、过滤信息(Filtering) 57、状态码(StatusCodes) 58、错误处理(Errorhandling) 69、返回结果(Response) 610、使用HATEOAS得HypermediaAPI 611、认证(Authentication) 7三、SwaggerAPI标准 7REST,即RepresentationalStateTransfer得缩写。RESTful架构,就是目前最流行得一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便,基于这个风格设计得软件可以更简洁,更有层次,更易于实现缓存等机制,所以正得到越来越多网站得采用。如果一个架构符合REST原则,就称它为RESTful架构。本文即将描述得,即就是创建RESTful架构得API所要遵循得原则与规范。一、背景与基础概念Web应用程序最重要得REST原则就是,客户端与服务器之间得交互在请求之间就是无状态得。从客户端到服务器得每个请求都必须包含理解请求所必需得信息。资源(resource):网络上得一个实体或者说就是一个具体信息,可以就是一段文本、一张图片、一首歌曲、一种服务。统一资源定位符(URI,UniversalResourceIdentifier):一个资源得识别符或者说就是一个地址,通过URI您可以定位到特定得资源。要获取这个资源,需要访问它得URI,因此,URI就成了每一个资源得地址或独一无二得识别符。状态转换(StateTransfer):所有资源都共享统一得接口,以便在客户端与服务器之间传输状态。客户端与服务器互动得过程,通常涉及到服务器端数据与状态得变化过程,比如文件被修改,访问数量增加等。使用得就是标准得HTTP方法,Http标准中定义得最主要四个动词:GET、POST、PUT、DELETE。它们分别对应四种基本操作:GET:用来获取资源POST:用来新建资源PUT:用来更新资源DELETE:用来删除资源Hypermedia 就是应用程序状态得引擎,资源表示通过超链接互联。二、RESTfulAPI应遵循得原则1、协议(Protocol)API与用户得通信协议,尽量使用HTTPs协议。HTTPs协议得所有信息都就是加密传播,第三方无法窃听,具有校验机制,一旦被篡改,通信双方会立刻发现,配备身份证书,防止身份被冒充。2、域名(ROOTURL)应该尽量将API部署在专用域名之下。如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下。3、版本(Versioning)应该将API得版本号放入URL。另一种做法就是,将版本号放在HTTP头信息中,但不如放入URL方便与直观。Github采用这种做法。注:需要注意版本规划,以便以后API得升级与维护。使得API版本变得强制性,不要发布无版本得API,使用简单数字,避免小数点如2、5。4、路径(Endpoints)路径表示API得具体网址URL。在RESTful架构中,每个URL代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用得名词往往与代表得对象名称对应。一般来说,某一同种记录得”集合”(collection),所以API中得名词也应该使用复数。具体细则:1、使用名词而不就是动词。举例来说,某个URL就是/cards/show/1,其中show就是动词,这个URL就设计错了,正确得写法应该就是/cards/1,然后用GET方法表示show。如果某些动作就是HTTP动词表示不了得,您就应该把动作做成一种资源。比如网上汇款,从账户1向账户2汇款500元,错误得URI就是:POST/accounts/1/transfer/500/to/2。正确得写法就是把动词transfer改成名词transaction,资源不能就是动词,但就是可以就是一种服务:POST/transaction?from=1&to=2&amount=500、00。2、使用复数名词。不要混淆名词单数与复数,为了保持简单,只对所有资源使用复数。举例:/cars而不就是/car/users而不就是/user/products而不就是/product/settings而不就是/setting3、使用子资源表达关系。如果一个资源与另外一个资源有关系,使用子资源。举例:GET/cars/911/drivers/返回car911得所有司机GET/cars/911/drivers/8返回car911得8号司机5、HTTP动词(HTTPVer