5 个基本的 REST API 设计指导方针

当我们开始从事API开发的时候，设计问题便出现了. 一个强而有力的API设计方法是API成功的关键要素. 设计糟糕的API会导致API滥用问题，或者更糟：API根本没人使用 (指Web开发者).

建立和提供一个艺术品级别的API需要考虑一下几点:

• 使用如部分资料中所描述的RESTful API原则 (Roy Fielding, Martin Fowler, HTTP 规范等).
• 参考Web巨头的做法，例如Google, Microsoft, Facebook, PayPal 和其他大公司.

关于如何设计一个REST 风格的API这个问题，目前没有通用答案. 而REST 风格的最佳实践这个问题仍然处于辩论和巩固中，这就是为什么这项工作很迷人的原因.

第 1 段（可获 1.51 积分）

0lison2个月前

URI 命名

涉及到给项目中的资源明明时，有三种主要的命名约定方式: 驼峰命名法（CamelCase）, 蛇形命名法（snake_case）, 和 脊柱形命名法（spinal-case）. 这些命名法则类似于我们使用的自然语言，他们只是一种命名资源的方式，使用他们时要避免引入空格，撇号等特殊字符. 这些法则在编程语言中很通用，因为他们只使用一组有限的特性为变量命名.

驼峰命名法（CamelCase）

驼峰命名法在Java语言中很流行 !?. 它将每个单词的首字母大写，例如 camelCase, currentUser,等. 抛弃对这种命名法的可读性的争议，它主要的缺点是在大小写不敏感的上下文中这种方式命名的不同变量来讲是无效的（有些语言是忽略大小写的，例如T-SQL的变量声明）.

第 3 段（可获 1.41 积分）

0lison2个月前

根据文档 RFC3986 规定, URL是大小写敏感的 (除了主机头等信息).
实际情况中，大小写敏感问题可能会对在Windows环境托管的API导致出现问题.

所以建议使用脊柱命名法（spinal-case） ( RFC3986 文档中突出强调了这一点), 这种命名法也被 Google, PayPal 和其他大公司使用.

2. HTTP 方法

如前所述, 建立一个REST风格的API 的主要关键目标之一是使用HTTP协议作为应用程序的协议，从而避免制作出“土造”的REST风格API（好难翻）. 因此, 我们应当系统的使用HTTP谓词来描述对资源所要执行的操作，并且让开发人员可以方便的处理重复的CRUD操作.

第 5 段（可获 1.35 积分）

0learner2个月前

OPTIONS

描述目标资源的通信参数.

3. HTTP头

HTTP头的字段提供了有关请求或应答必要的信息,或者提供了有关消息体重发送的对象的信息.

HTTP消息头有4种类型:

1. 一般头: 这些头的字段对请求和响应消息有通用性.

2. 客户端请求头: 这些头的字段只能应用于请求消息.

3. 服务器响应头: 这些头的字段只能应用于响应消息.

4. 实体头:这些头的字段定义了有关实体正文的元信息,如果这儿没有正文,则定义有关请求确认的资源的元信息

第 7 段（可获 1.28 积分）

0KeYIKeYI2天前

排序

排序是指在集合资源上的查询结果进行排序.排序参数需要包含进行排序的字段的名字,并以逗号隔开.

搜索

搜索是一个集合的子资源.因此,搜索的结果有与资源和集合本身不同的格式.这使得我们可以添加建议,修正和与该搜索相关的其他信息.搜索提供参数的方式与过滤相同----都是通过查询参数,但是搜索参数不需要精确的值,并且搜索参数的语言允许近似匹配.

第 9 段（可获 1.2 积分）

0lison2个月前

403 – FORBIDDEN: 拒绝访问.

404 – NOT FOUND: 找不到文件.

500 – INTERNAL SERVER ERROR: API 开发者应当避免这种错误. 如果这种错误在全局异常中被捕获, stack trace会记录下这个错误并且不会返回响应内容.

总结

REST 不是个新事物. REST 是大型应用服务器所用各式各样获取数据方式的一种回归, 通过它来强调早期的Internet，URI标准和HTTP标准（返璞归真，阿弥陀佛）.

资源建模（指REST风格API设计）需要基于业务需求做仔细考虑, 技术开发注意事项（纯粹的架构设计，可维护性等）和成本效益分析等前面已经讨论过的各种各样的方法，通过做这些以便创造出更加易于用户体验的API.