任何人都有一个“定义良好"的例子.REST 网络服务? [英] Anyone has an example of a "Well Defined" REST Web Service?

问题描述

我阅读了大量关于 REST 与 SOAP 辩论的帖子、问题和答案.我读到一些 REST 支持者声称精心设计"的 REST Web 服务是不言自明的，几乎不需要任何文档.

I read tons of posts, questions and answers on the REST vs SOAP debate. I read a few REST supporters that claim that "well designed" REST Web Services are self explanatory and hardly need any documentation.

谁能告诉我这样的网络服务?最好是有点复杂的.

Can anyone point me to such a Web Service? Preferably a somewhat complicated one.

推荐答案

我发现 Netflix 的文档非常好，并帮助您了解设计 API 的内容.API 并不完美，但我认为它是实用和周到的很好的结合.

I found Netflix's documentation to be very good and help you understand what goes into designing an API. The API is not perfect, but I think it is a good combination of practical and thoughtful.

自记录 REST API 的想法是，可以为系统提供单个入口点，并能够通过返回的文档发现所有可用的功能，并结合对 REST 动词(GET、放置，删除).这样，如果您从 RESTful 系统中提取员工列表，各个条目将指向该条目的 URL，而雇主字段将指向雇主的 URL.搜索 HATEOAS 了解更多详情.但是您可能会在服务上调用/employee"并得到:

The idea of a self documenting REST API is that one can be given a single entry point into a system and be able to discover all functionality available through the returned documents, combined with understanding of standard usage of the REST verbs (GET, PUT, DELETE). So that if you pulled up a list of employees from a RESTful system, the individual entries would point to the URL of that entry and the employer field would point to the URL for the employer. Do a search on HATEOAS for more details. But you might call "/employee" on a service and get:

<employees>
  <employee id=132 name=bob url="/employee/132" employer="/employer/176"/>
  <employee id=179 name=carl url="/employee/132" employer="/employer/122"/>
</employees>

您可以在/employee/132 查看完整的员工记录，并在/employer/176 查看其雇主的记录.按照惯例，如果您有权限，您可以使用 PUT 对/employee/132 更新员工 bob，或使用 POST 到/employee 创建新员工.接受的内容类型也可以通过界面查询(我相信使用 HEAD).

You could view the complete employee record at /employee/132 and view the record of their employer at /employer/176. By convention, if you had permission, you could update the employee bob using PUT against /employee/132 or create a new employee with a POST to /employee. The content types accepted are queryable through the interface, also (using HEAD, I believe).

这篇关于任何人都有一个“定义良好"的例子.REST 网络服务?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！