RESTful api

[pengkobe]

为什么会有 RESTful API？

必须有一种统一的机制，方便不同的前端设备与后端进行通信，以降低开发的复杂性，提高系统的可伸缩性。

名词解释

全名翻译为: Representational State Transfer

• Resources：资源，网络上的一个具体信息( text/img/vedio/service... )，用 URI 来表示
• Representational：表现层，资源具体呈现出来的形式，在服务器客户端来回传递
• State Transfer：状态转化，对 HTTP 来说，其实就是 GET/POST/PUT/DELETE，所有的操作都是无状态的

设计误区

• URI 包含动词，post/show/resource中使用到了 show，想办法把动词转换为名次才是正确的做法
• 在 URI 中加入版本号， 版本号可以在 HTTP 请求头信息的 Accept 字段中进行区分

设计指南

• 使用 HTTPs 协议
• 将 API 部署在专用域名之下，如api.xxx.com
• 将版本放置 URL 中，如api.xxx.com/v1
• 所以 API 中的名词也应该使用复数

示例

• 信息过滤示例： ?sortby=name&order=asc,指定返回结果按照哪个属性排序，以及排序顺序。、
• 错误处理格式示例：{error: "Invalid API key"},采取简单的键值对形式就行
• 使用 Hypermedia API，如 Github 会这么做 { "current_user_url": "https://api.github.com/user", "authorizations_url": "https://api.github.com/authorizations", // ... }

返回结果

GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回一个空文档

其它

• API的身份认证应该使用 OAuth 2.0 框架。
• 服务器返回的数据格式，应该尽量使用 JSON，避免使用 XML。

RESTful 与 webService

本质

• RESTful 是一种架构风格，其核心是面向资源
• webService 底层 SOAP 协议，主要核心是面向活动

SOAP vs REST

• SOAP 是协议，定义了安全，事务等各个方面的内容，同时 SOAP 强调操作方法和操作对象的分离，有WSDL 文件规范和 XSD 文件分别对其定义。
• REST 不是什么协议也不是什么标准，而是将 Http 协议的设计初衷作了诠释

使用场景

• RESTful ：简单数据操作，无事务处理，开发和调用简单
• webService： 主要目标是跨平台的可互操作性，主要针对较为复杂的面向活动的服务

参考

• 理解RESTful架构
• RESTful API 设计指南
• Restful与webService区别

深入阅读

Versioning REST Services

[pengkobe]

摘抄自: webservice soap简介及应用场景

趣味理解

Web Service 好比一个服务供应商，给其他厂家提供基础服务，其他厂家再将这个服务包装成自己的产品或者服务提供给别人或自己使用。有点像 OEM 了。既然两个公司需要合作，不可能靠一句话就可以的，就需要一些标准和规范的东西来实现。那么：

SOAP

就像两个公司之间签的合同，约束双方按一定规矩和标准办事。

WSDL

则像说明书，告诉别人你有什么，能给别人提供什么服务。

UDDI

好比你的公司需要在黄页或工商注册，企业的主营业务登记，方便别人查询。当然，你也可以不在 UDDI 中注册，就像在地下室开展业务，靠的是口头吆喝；但是如果你希望拓展市场，则需要 UDDI 以便能被客户发现，更方便地找到你。

总结

Web Service是创建可互操作的分布式应用程序的新平台。Web Service 的主要目标是跨平台的可互操作性。为了达到这一目标，Web Service 是完全基于XML、XSD等独立于平台、独立于软件供应商的标准的。Web Service在应用程序跨平台和跨网络进行通信的时候是非常有用的。Web Service适用于应用程序集成、B2B集成、代码和数据重用，以及通过Web进行客户端和服务器的通信的场合。

非万能

当然，Web Service也不是万能的，你不能到处滥用Web Service。在有些情况下，Web Service 会降低应用程序的性能，而不会带来任何好处。例如，一台机器或一个局域网里面运行的同构应用程序就不应该用Web Service 进行通信。