我刚刚读完 Restful Web Services 和 没有人理解 REST 或 HTTP 和我正在尝试使用 RESTful 设计来设计一个 API。
我注意到API URI设计中的几个模式：
http://api.example.com/users
http://example.com/api/users
http://example.com/users
假设这些设计正确使用 ACCEPT 和 content-type XHTML、JSON 或任何格式之间的内容协商。
这些 URI 是纯粹 RESTful 实现还是隐式内容协商的问题？
我的想法是，通过在 URI 中显式使用 API，客户端会期望一种本质上不令人愉悦的超媒体数据格式，并且可以更轻松地使用，而无需显式设置 Accept 标头。换句话说，API 暗示您需要 JSON 或 XML，而不是 XHTML。
这是分离资源表示的问题吗
逻辑上在服务器端？
对于为什么有人会使用 API 子域来设计 URI，我能想到的唯一理由是，基于我的假设，这是一种扩展技术，它应该使多层服务器基础设施中的路由请求加载变得更容易。也许存在反向代理剥离标头的情况？我不知道。不同的服务器处理不同的表示？
也许子域仅用于外部使用者，以便服务器避免内部使用的开销。限速？
我是不是漏掉了一点？
我提出的设计将尝试遵循 RESTful 实践，设置适当的标头、适当使用 HTTP 动词并以我认为在 URI 中包含“API”的方式表示资源。
为什么有人会设计一个在 URI 中包含“API”的 RESTful API？
或者他们可以吗？也许我不理解这个设计的问题是，只要它遵循某种可能不会导致 RESTful API 实现但接近的规范组合，没关系？ 给键盘猫剥皮的方法不止一种。
HATEOAS 相关吗？
更新：在研究这个主题时，我得出的结论是，考虑 REST 的想法很重要，但不要将其视为一种宗教。因此，URI 中是否包含“api”更多的是一个设计决策，而不是一个坚定的规则。如果您计划公开公开网站的 API，那么使用 api 子域来帮助处理应用程序的逻辑是个好主意。我希望有人能贡献自己的见解，供其他人学习。
I just finished reading Restful Web Services and Nobody Understands REST or HTTP and am trying to design an API with a RESTful design.
I've noticed a few patterns in API URI design:
http://api.example.com/users
http://example.com/api/users
http://example.com/users
Assume that these designs properly use Accept and Content-type headers for content negotiations between XHTML, JSON, or any format.
Are these URI's a matter of a pure RESTful implementation vs implicit content negotiation?
My thoughts are that by explicitly using API in the URI is so that a client will expect a data format that is not inherently human pleasing hypermedia and can be more easily consumed without explicitly setting an Accept header. In other words, the API is implying that you expect JSON or XML rather than XHTML.
Is this a matter of separating resource representations
logically on the server side?
The only justification I can come up with for why someone would design their URI's with an API subdomain is because, based off my assumption that this is a scaling technique, it should make routing request load easier in a multi-tiered server infrastructure. Maybe situations exist where reverse proxies are stripping the headers? I don't know. Different servers handling different representations?
Maybe a subdomain is used for external consumers only so that the server avoids the overhead from internal usage. Rate limiting?
Am I missing a point?
My proposed design would attempt to follow RESTful practices by setting appropriate headers, using HTTP verbs appropriately and representing resources in a fashion that I feel including 'API' in the URI would be redundant.
Why would someone design a RESTful API with 'API' in the URI?
Or could they? Maybe my problem with not understanding this design is that it doesn't matter as long as it follows some combination of specification which may not lead to a RESTful API implementation but close? There is more than one way to skin a keyboard cat.
HATEOAS related?
Update: While researching this topic I have come to the conclusion that it's important to consider ideas from REST but not to treat it as a religion. Thus, whether or not to have 'api' in the URI is more of a design decision than a steadfast rule. If you plan to expose your website's API publicly it would be a good idea to use an api subdomain to help deal with the application's logic. I hope that someone will contribute their insight for others to learn from.
发布评论
评论（4）
我会（并且已经）这样做是为了将其与“网站”基础设施分开，因为它可能会具有更高的负载并需要更多的基础设施 - 每天进行数百万个 API 调用比在页面视图中获取要容易得多，因为您拥有 n 个网站/公司的全部负载以及他们的努力和吸引力，集体甚至在某些情况下单独他们将吸引比您自己更多的流量。
I would (and have) done it to separate it from the 'website' infrastructure because it's probably going to have a higher load and require more infrastructure - it's a lot easier to do millions of API calls a day than get that in page views because you have the full load of n sites/companies and their efforts and traction, collectively and even in some cases individually they're going to attract more traffic than you yourself.
对于你的问题，我的理解和观点是：
不，它们不属于任何官方文档（据我所知），并且通常由开发人员/团队标准自行决定。例如，Zend Framework 使用一些实用程序类来检测 XHR 请求以及如何返回响应。诚然，ZF 不是纯粹的 RESTful 设计（或者事实上大多数 PHP 应用程序），但即使在 PHP 中仍然可以编写此类设计。
我经常看到在 url 中使用
api，而预期返回的数据确实不打算按原样用于显示给最终用户。然而，这通常是一个设计决策，并不一定是一个隐含的标准。或多或少。例如，当执行
PUT请求时，界面不一定需要完全刷新，通常一个简单的响应消息就足够了。虽然此响应消息是视图的一部分，但它不是视图。因此，例如，http://domay.com/users/将返回管理用户（或其他）的接口，http://domain.com/users/apicode> 将执行操作并返回界面更新（无需重新加载页面）。嗯，不。由于在 URL 中使用或不使用
api是一个设计决策，因此您不会遗漏任何内容。有了正确的标头，所有的请求都可以是有效的 RESTful 请求。
简单地说，就是有一个 URL 命名约定。这样，当查看日志、文档等中的请求时，人们就会理解它的目的。
This is my understanding and point of view about your question :
No, they are not part of any official documentation (that I know of), and are usually at the developper/team standards discretion. For example, Zend Framework uses some utility classes to detect XHR requests and how responses should be returned. Granted, ZF is not pure RESTful design (or most PHP application as a matter of fact), but it is still possible to write such designs even in PHP.
I have often seen
apibeing used in urls when the returned data expected is indeed not meant to be used as is for display to the end user. However it is usually a design decision and not necessarily an implied standard.More or less. For example, when performing a
PUTrequest, for example, the interface does not necessarily need to be entirely refreshed, and often a simple response message is good enough. While this response message is part of the view, it is not the view. So, for example,http://domay.com/users/would return the interface to manage users (or whatever),http://domain.com/users/apiwould perform operations and return interface updates (without a page reload).Weell, no. Since it is a design decision to use or not
apiin the URL, you're not missing anything here. With the proper headers,can all be valid RESTful requests.
Simply put, to have an URL naming convention. So that, when looking at a request in logs, documentation, etc. One will understand it's purpose.
另请记住，大多数框架（django、RoR...）都提供开箱即用的基于 URL 的路由。您可能需要 API 与 HTML 响应的不同视图来以不同方式管理身份验证、小跑、限制检查和其他特定内容等内容。
正如您所说，建立一个额外的基于 HTTP 标头的路由系统来允许隐式内容协商通常是不值得的。
Also keep in mind, that most frameworks (django, RoR,...) provide URL-based routing out of the box. You probably need different views for API vs. HTML responses to manage things like authentication, trotting, limits-check and other specific stuff differently.
Putting in place an additional HTTP-Header based routing system to allow, as you say, implicit content negotiation is often not worth the effort.
用户可见的网页 URL 受到网站管理员、设计师、公司组织、营销、时尚、技术等的突发奇想的影响。
另一方面，API 应该保持稳定。通过使用子域，您可以将 API 与网站的其余部分及其可能及时发生的更改隔离开来。
User-visible webpage URLs are subject to the whims of webmasters, designers, corporate organization, marketing, fashion, technology, etc.
An API, on the other hand, is supposed to remain stable. By using a subdomain you isolate your API from the rest of the website and the changes it is likely to undergo in time.