RESTful API 应该是完全可发现和自动记录的。您只需要一个URL,链接到它的其他所有内容都应该描述自己。听起来像一个乌托邦,但这是可行的。
例如,让我们从一个类似堆栈溢出的示例 URL 开始:http://restfuloverflow.com(说明性)
您对 RESTful 资源执行的第一件事是 OPTIONS 请求。您始终需要包含 Accept 标头以指示服务器响应最合适的 mime 类型:
OPTIONS * HTTP/1.1
Accept: text/html, text/xml, application/json
Host: restfuloverflow.com
服务器应指示客户端在该 URL 上可以执行的操作:
HTTP/1.1 200 Ok
Allow: GET, POST, PUT, DELETE, OPTIONS, TRACE, PATCH
这是RESTful API告诉您此服务支持这些方法。您将尝试的第一个请求类似于下面的请求。使用浏览器点击 API 的用户应以类似的方式工作。
GET / HTTP/1.1
Accept: text/html, text/xml, application/json
Host: restfuloverflow.com
然后,服务器应返回一些指向相关资源的链接(如果可用):
HTTP/1.1 200 Ok
Content-Type: text/xml
<?xml version="1.0">
<qa>
<link href="/questions" title="Questions"/>
<link href="/tags" title="Tags"/>
<link href="/users" title="Users"/>
</qa>
HTML 版本应使用链接,JSON 响应应使用 JSON 架构属性。<a>
links
假设客户端现在决定它想知道如何处理问题:
OPTIONS /questions HTTP/1.1
Host: restfuloverflow.com
Accept: text/html, text/xml, application/json
可能的响应可能是:
HTTP/1.1 200 Ok
Allow: GET, POST
Content-Type: text/xml
<?xml version="1.0">
<xsd:element name="question">
<!-- XML Schema describing a question -->
</xsd:element>
好吧,服务器告诉我们,可以获取并发布一个新问题。它还通过提供 XML 架构告诉我们 XML 中的问题是什么样子的。可以为JSON提供JSON-SCHEMA,并在HTML中为新问题提供表单。
假设用户想要 GET 问题:
GET /questions HTTP/1.1
Host: restfuloverflow.com
Accept: text/html, text/xml, application/json
然后服务器响应:
HTTP/1.1 200 Ok
Content-Type: text/xml
<?xml version="1.0">
<questions>
<link href="/questions/intersting" title="Intersting Questions"/>
<link href="/questions/hot" title="Hot Questions"/>
</questions>
现在,一切都再次链接在一起。事情以服务描述自己的方式持续进行。Netflix API遵循类似的原则,但缺乏一些自动发现功能。
这个巴西政府API使用RDF来描述自己。这是我见过的最好的RESTful样品之一。尝试将 .rdf 更改为 .xml、.json 或 .html。(这都是葡萄牙语,很抱歉)。
PHP中RESTful API的最佳工具是Respect\Rest。它具有我在这里描述的大部分工作流程已经引导,并且新功能即将推出(它仍然是0.4x版本)。
为RESTful应用程序构建文档系统的成本与构建RESTful应用程序的成本相同。这就是为什么像这样的工具如此之少,而且通常它们并不那么好。