构建 RESTful API 的最佳实践 在构建 RESTful API 时，遵循最佳实践至关重要，以确保 API 的可维护性、可扩展性和健壮性。以下是构建 RESTful API 的 10个最佳实践： 1. 使用描述性和有意义的资源名称 资源名称应准确表示所代表的实体。避免使用泛泛或模糊的名称。例如，使用“/users”而不是“/data”。 2. 正确使用 HTTP 方法 针对不同的操作使用适当的 HTTP 方法。 GET：用于检索资源 POST：用于创建资源 PUT：用于更新整个资源 PATCH：用于更新资源的特定部分 DELETE：用于删除资源 3. 为 API 进行版本控制 通过版本控制来确保向后兼容性，同时能够在不破坏现有客户端的情况下进行未来的增强。 4. 正确使用 HTTP 状态码 返回适当的 HTTP 状态码来指示 API 请求的成功或失败。例如： 200 OK：请求成功 400 Bad Request：请求不合法 404 Not Found：资源不存在 500 Internal Server Error：服务器出现错误 5. 选择 JSON 字段命名约定（并坚持使用） 虽然 JSON 标准没有强制规定字段命名约定，但根据最佳实践，我们应该选择一种字段命名约定，并坚持使用。例如，可以使用下划线分隔词或驼峰式大小写。 6. 使用一致的错误消息 在大多数情况下，仅仅依靠 HTTP 状态码无法很好地解释错误的原因。为了帮助 API 使用者，应该提供结构化的 JSON 错误消息。这样可以更清楚地说明错误的具体原因。响应应包含以下信息： 错误代码：唯一的错误标识符 错误消息：错误的描述性文本 调试信息：帮助开发人员调试问题的附加信息（可选） 7. 使用查询参数进行过滤、排序和搜索 查询参数支持在 HTTP 请求的 URL 中提供附加信息，以便控制服务器返回的响应。通过使用查询参数，可以定制您所需的特定结果。例如： /users?filter=active=true&sort=name&search=john 8. 实现身份验证和授权 通过实施适当的身份验证和授权机制来保护 API。这是为了确保只有经过授权的用户才能访问敏感数据或执行操作。 9. 不要维护状态 RESTful API 不应该在服务器上维护状态，这是客户端的责任。这一点非常重要，因为它使 API 可以进行缓存、可扩展，并且与客户端解耦。 10. 文档化 API 为 API 提供全面的文档，包括： 端点详细信息 请求/响应示例 使用指南 错误代码列表 版本历史记录 通过遵循这些最佳实践，您可以构建可维护、可扩展且健壮的 RESTful API，为您的用户提供卓越的体验。

---

如何编写Floodlight REST 应用

可以用任何你喜欢的编程语言编写REST应用，参照以下步骤：1、确定需求，也就是你编写的REST应用需要哪些网络服务和信息。 2、检查REST API，看看是否有提供你所需的服务。 a、如果有，了解其RESTAPI的语法，输入的参数以及可得的选项，这样就可以直接拿来用。 b、如果没有，也可能是你所需的网络服务和资源信息没有提供REST API，但却可以在floodlight模块中可获得这些信息，只是没通过API暴露出来。 这种情况，你可以自己实现REST API来提供你所需的服务。 c、如果既没有REST API，又在floodlight中找不到，那你可以自己开发floodlight Java模块，并且实现自定义的模块的REST API来提供所需的服务。 3、用所有你需要的REST API方法，设计以及组成你的应用。 4、测试你的应用并且反馈给floodlight。 下面通过在floodlight/apps目录下的 Python Circuit Pusher应用说明。 Curcuit Pusher例子给我们展示了如何创建一个在OpenFlow集群中的两个有IP的主机A和B之间的静态单路径线路。

讨RESTAPI设计方面的最佳实践

由于REST可以降低开发的复杂度，提高系统的可伸缩性，增强系统的可扩展性，简化应用系统之间的集成，因而得到了广大开发人员的喜爱，同时得到了业界广泛的支持。比如IBM，Google等公司的很多产品都提供了REST API给开发人员；与此同时，大量的开源项目和云计算服务都提供了REST API接口。

而在最近，一些新产品的开发甚至已经几乎完全抛弃了传统的类似JSP的技术， 转而大量使用REST风格的构架设计， 即在服务器端所有商业逻辑都以REST API的方式暴露给客户端， 所有浏览器用户界面使用widget、Ajax、HTML5 等技术，用HTTP的方式与后台直接交互。

那么， 在REST API爆炸式增长的今天， 我们应该如何更好的设计我们的接口， 来提高我们的API的可用性，易用性，可维护性与可扩展性呢？本文将从以下方面与您探讨REST API设计方面的最佳实践：

如何规划资源标识结构与URI模式

如何根据应用场景提供内容协商

如何正确的使用HTTP响应代码

如何处理缓存和并发请求

如何利用数据冗余和链接元素

先决条件

如果您具有如下知识与经验，将有助于您阅读和理解本文章的内容 。

REST相关的基本知识；

HTTP协议的基本知识；

一定的Web开发经验。

REST简介

REST是英文 State Transfer的缩写，是近年来迅速兴起的，一种基于HTTP、URI以及XML这些现有协议与标准的，针对网络应用的设计和开发方式。它可以降低开发的复杂度，提高系统的可伸缩性。

REST的核心是可编辑的资源及其集合，用符合Atom文档标准的Feed和Entry表示。每个资源或者集合有一个惟一的URI。系统以资源为中心，构建并提供一系列的Web服务。REST的基本概念和原则包括：系统上的所有事物都被抽象为资源；每个资源对应唯一的资源标识；对资源的操作不会改变资源标识本身；所有的操作都是无状态的；等等。

在REST中，开发人员显式地使用HTTP方法，对系统资源进行创建、读取、更新和删除的操作：

使用POST方法在服务器上创建资源

使用GET方法从服务器检索某个资源或者资源集合

使用PUT方法对服务器的现有资源进行更新

使用DELETE方法删除服务器的某个资源

图 1. 用 HTTP 方法操作相册系统资源的简单范例

更好的规划你的资源标识结构与URI模式

REST 中，最基本的莫过于资源标识结构和URI模式了。更好的规划他们，是我们的API设计取得成功的最关键的一步。

首先，我们来看看基本资源类型

上文中提到，在REST构架的设计中，系统中的所有事物都被抽象为资源。

在一个文档系统中，文档、目录、注释、草稿等等，是组成系统的资源。

在一个银行系统中，客户信息、理财产品、利率信息、网点信息等等，是组成系统的资源。

在一个航空客票系统中，旅客信息、机票订单、航班信息、机场信息等等，是组成系统的资源。

这些资源，通常在系统中以“Entry”的形式出现。下面的代码样例向您展示了一个常见的“Entry”资源。

清单 1. 一个简单的Entry资源样例

以下是引用片段：

REST API 请求：

GET example/航班信息/CA827/entry

2010-08-24T02:35:40.937Z

2010-08-24T02:35:40.937Z

我们会注意到，这些资源，在描述了某种事物的同时，还有可能存在一定的层次结构关系。比如，文档从属于某个目录，注释从属于文档；旅客信息可以从属于机票订单，也可以从属于某个航班。

当我们的资源有这种层次关系的时候，我们不妨在URI模式的设计中，用复合的URI来帮助开发者更好的理解和设计资源。

比如， 针对一个文档的评论， 他的URI模式可以设计成如下：/文件夹/[文件夹名]/文件/[文件名]/评论/[ 评论唯一标示 ]。 这样，在构造和解析URI的过程中， 可以帮助开发者更好的理解系统，设计程序。

其次，我们来看看集合资源类型

资源，除了作为独立个体可以被访问，还可以由多个个体组合成一个集合，在系统中，通常以“feed”的形式存在。资源的集合， 可以是处于相同层次上，有相同从属关系的一组资源，比如一个文件夹下的所有文件； 也可以是根据某种条件查询出来的查询结果的资源集合，比如所有30岁以上40岁以下，拥有100万资产以上客户的名单。

下面，我们来讨论一下设计集合类型资源的REST API时需要考虑的问题。

使用过滤条件来帮助用户更准确地获取数据

我们要返回的资源集合，无论是否有相同从属关系，大部分时候都需要进行必要的过滤，提供足够的过滤参数，查询参数， 能够帮助开发者高效的，准确地获取所需要的数据。 在服务器端过滤数据通常比客户端高效，并且减少了不必要的数据传输，可以大大减少网络开销，提高执行效率。

最常见的过滤条件，是通过URL参数实现，比如/环境工程系/学生?籍贯=北京&性别=女。

很多时候，我们需要制定更加复杂的过滤条件，那么我们可以有两种选择：

首先，我们可以使用正则表达式或者服务器可以理解的语法，比如/环境工程系/学生?filter=age between (15, 18)

其次，我们还可以使用POST方法，携带一个文件来描述复杂的查询条件，文件的格式与语法通常需要在服务器端有相应的设计与定义。不过通常POST方法没有缓存机制，因此不是查询数据的首选。

使用排序来帮助客户端更好的展现数据

虽然进行客户端排序对于开发者来说是件轻而易举的事情，但是直接得到已经排序的返回结果，仍然是大部分开发者所期望的。尤其是很多时候，我们在浏览器，使用 Widget 展示结果，不适宜在客户端存储大量数据进行内存排序。

排序， 通常有2个参数，一个是用来排序的字段，一个是排序的升序降续方式。比如我们可以用支持这样的参数组合的手段，提供基本的排序能力：?sortOrder=asc&sortField=age

使用分页来帮助客户端处理大量数据

由于返回的结果可能有几百几千条记录，将这些记录一次性的返回给客户端是不现实的，巨大的网络流量开销和客户端数据区的内存开销，都是我们在应用开发的时候不希望看到的，因此，如果你的集合资源有可能有大量的数据返回，请务必提供分页的功能支持。

我们通常用一个以上参数来制定一个返回结果的区域，比较常见的有下面两种：

一种常见于用固定行数的表格来展示数据，用当前处于第几页和每页返回多少行数据来确定需要的数据， 比如/所有学生?page=5&pagesize=50

另外一种常见于用更加灵活的界面展示数据，用从第几行开始，一共返回多少行数据来确定需要的数据， 比如/所有学生?startIndex=27&count=22

下面是一个来自IBM 的API样例，尝试请求该API，你可以看到该集合很好的支持了结果的分页与排序。同时我们从返回的信息中可以看到，每个文档Entry的URI都按照/社区库/[社区库ID]/文档/[文档ID]的复合URI的模式设计的。

清单 2. IBM 的某个社区文件库的集合资源的API

以下是引用片段：

REST API 请求：

GETIBM 的文件服务标签云的API

以下是引用片段：

REST API请求，要求返回XML格式数据：

/files/form/anonymous/api/tags/feed?format=json

&scope=document&pageSize=30&sK=cloud&sO=dsc

使用Aept头进行内容协商

使用URL参数，简单灵活，但是也由此带来了设计上的随意和不标准。并且，过多的参数会导致URL的可读性变差，更有甚者，可能会导致URL过长，超出规范，API请求无法执行。

更为标准的内容协商方式是使用HTTP头。我们通常使用Aept来设置我们接受的返回结果的内容格式，用Aept-Charset来设置字符集，用Aept-Encoding来设置数据传输格式，用Aept-Language来设置语言。

使用URI模式进行内容协商

还有一种模式，就是将协商设置直接作为URI的一部分，将不同的返回视为不同的资源，比如/航班号/json来返回JSON格式的结果，用/航班号/atom来返回ATOM格式的结果。

正确的使用HTTP响应代码

作为API的设计者，正确的将API执行结果和失败原因用清晰简洁的方式传达给客户程序是十分关键的一步。 我们确实可以在HTTP的相应内容中描述是否成功，如果出错是因为什么， 然而， 这就意味着用户需要进行内容解析，才知道执行结果和错误原因。因此，HTTP响应代码可以保证客户端在第一时间用最高效的方式获知API运行结果，并采取相应动作。

转载，仅供参考，祝你愉快，满意请采纳。