如何更好的设计RESTful API

Posted 2023-04-19

　一个好的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的可伸缩性会有很多问题。 参考技术A 1.接口命名规则
http://ip:端口/v1/接口名
IP：服务器IP地址
端口：Restful端口号
V1：版本号(1)
接口名：
命名规则：现有接口方法去第一个单词后，全小写命名，如：
城市信息查询， 原接口名：queryCityId (String id)
Restful接口：http://ip:端口/v1/cityid\
2.参数规则
参数提交方式：Application/www-form-urlencoded
参数命名：单词采取小写，复合词采取下划线分开的全小写命名。
参数规则：批量查询需有page_size以及page_num参数，避免一次性查询，部分参数需有默认值设定。
Restful接口设计原则
l 使用标准HTTP方法实现资源CURD操作；
l 采用json作为API输入输出；
l 以json输出错误信息。
注：Http协议详解
HTTP请求方法在 RESTfulAPI 中的典型应用
一组资源的URI，比如
http://ip:8080/v1/ user/
列出 URI，以及该资源组中每个资源的详细信息（后者可选）。
使用给定的一组资源替换当前整组资源。
在本组资源中创建/追加一个新的资源。该操作往往返回新资源的URL。
删除 整组资源。
单个资源的URI，比如
http://ip:8080/v1/user/1
获取 指定的资源的详细信息，格式使用JSON
替换/创建 指定的资源。并将其追加到相应的资源组中。
把指定的资源当做一个资源组，并在其下创建/追加一个新的元素，使其隶属于当前资源。
删除 指定的元素。
PUT 和 DELETE 方法是幂等方法。GET方法是安全方法 （不会对服务器端有修改，因此当然也是幂等的）。
支持的返回码列表：
HTTP返回码
实现举例
例如，一个简单的客户管理应用:
列举所有客户：
URL: GET http:// ip: 8080/v1/crm/customer
输入：无
输出：略
呈现某一位客户：
URL: GET http:// ip: 8080/v1/crm/customer/[customer id]
输入：无
输出：略
新增客户：
URL: POST http:// ip: 8080/v1/crm/ customer
输入：略
输出：略
更新用户：
根据更新参数，需要更新哪些参数就选哪些参数。 参考技术B 确保安全性可以从三个方面去做： 对客户端做身份认证 对敏感的数据做加密，并且防止篡改 身份认证之后的授权 现在比较流行的是使用OAuth协议做身份认证

如何设计一个 RESTful API 来检查用户的凭据？

【中文标题】如何设计一个 RESTful API 来检查用户的凭据？

【英文标题】：How to design a RESTful API to check for user's credentials?

【发布时间】：2012-04-26 01:38:41

【问题描述】：

我正在为移动应用程序设计一个 API，我希望它保持 RESTful。 API 是使用 Basic HTTP Auth 授权的，但是，当用户第一次打开应用程序时，他需要先登录，所以我需要设计一个 API 来检查用户的凭据，它将接受一对用户名和密码，相应地返回成功或失败。 问题是网址应该是什么所以它很安静？我认为 /login 不是一个好方法。

【参考方案1】：

通过 HTTP GET 请求传递敏感数据通常被视为不好的做法。

密码信息是敏感数据，是违反idempotent operations 应为GET 请求规则的例外情况之一。

为什么这是一个例外？浏览器历史和服务器日志将存储GET 请求。这意味着此敏感信息在两个地方都以纯文本形式显示。因此，如果有人掌握了其中任何一个 - 那么该信息现在就在他们手中。

您应该使用 HTTP POST 请求将此敏感信息传递给 RESTful API，因为浏览器不会存储它们，服务器也不会记录它们。但是，第一道防线是使用安全 HTTP (HTTPS) 来确保这些信息不受外来者的影响。

因此，将 HTTP 请求的 正文 中的此信息传递给 HTTPS URL。

【参考方案2】：

一个好的方法是对当前用户的帐户/个人资料信息执行GET 请求。并让它返回用户名、设置、头像 url 等。me 是常用的身份验证用户的简写标识符。

GET https://api.example.com/profiles/me
HTTP/1.1 200 OK

  "username": "bob",
  "id": "xyz",
  "created_at": 123,
  "image_url": "https://example.com/bob.png"

【参考方案3】：

来自***：

客户端-服务器通信进一步受到没有客户端的限制 在请求之间存储在服务器上的上下文。每个请求来自 任何客户都包含服务所需的所有信息 请求，并且任何会话状态都保存在客户端中。

因为服务器不存储来自客户端的会话状态，所以您的 API 不应公开任何登录/注销功能：在每个请求中，您应该发送用户凭据，并且服务器每次都应该验证它们.

检查this discussion in SO，它阐明了这个概念。

【参考方案4】：

我同意 Carlos 的观点 - 在普通的 restful API 中，没有会话，因此您无法进行一次身份验证然后重用会话，您实际上需要在每次调用时传递凭据集（不理想）。

在这种情况下，听起来您最好使用其中一个 openAuth (http://www.oAuth.net) - 这通过在应用程序首次运行时进行身份验证然后生成访问令牌以允许访问来工作在每次调用中（+一个刷新令牌）。

（您可能会争辩说访问令牌是状态 - 它有点像 - 但是，至少它通常寿命明显更长）。

【讨论】：

是的，我在每次通话时都会通过设置的凭据，但是，当用户第一次打开应用程序时，我确实需要登录来检查用户的凭据

实际上，我没有保留会话 cookie 或类似的东西

好的 - 所以我猜你必须在每次调用时传递凭据 username / password 是正确的。您要么需要始终通过它，要么通过它一次并跟踪会话。

【参考方案5】：

GET https://api.example.com/auth

设置了授权标头。