文章目录
  1. 1. 如何编写RESTful Web服务的文档
  2. 2. 如何使用OPTIONS

当创建RESTful web服务时,需要解决设计时可发现性和运行时可发现性这两类可发现性。设计时可发现性有助于其他设计和创建客户端,它描述了客户端开发组和管理员用于构建和启动客户端的基本信息。运行时可发现性有助于维护客户端和服务器之间的松散耦合并使能即插即用式自动化。运行时可发现性解决了HTTP统一接口、媒体类型、链接和链接关系类型。本章是关于设计时可发现性的。

设计时发现简单来说就是将web服务用散文描述,不管这些散文诗有工具生成还是设计者手工写作。客户端开发者可以查询散文以理解资源语义、媒体类型、链接类型等信息以实现客户端。

如何编写RESTful Web服务的文档

下面这些信息需要在RESTful web服务文档中描述:

  1. 所有资源及每个资源支持的方法
  2. 请求和响应中资源的媒体类型和表述格式
  3. 使用的链接关系、商业意义、所用的HTTP方法及链接标识的资源
  4. 所用不通过链接提供的固定URI
  5. 用于所有固定URI的查询参数
  6. URI模板和符号替换规则
  7. 访问资源的认证和安全证书

对于XML表述,如果客户端和服务器支持XML schema,使用schema语言描述用于请求和响应中表述的XML结构。对于其他格式,使用散文描述表述。

如何使用OPTIONS

通过支持HTTP OPTIONS方法,有助于工具了解web服务中的资源。在服务器端,实现OPTIONS方法通过Allow头返回支持方法列表。当资源支持PATCH方法,添加Accept-Patch头列举支持PATCH请求的媒体类型。可选择性添加含有资源描述文档的链接的Link头。

文章目录
  1. 1. 如何编写RESTful Web服务的文档
  2. 2. 如何使用OPTIONS