[英]What's the best design for a RESTful URI with multiple mandatory parameters?
I'm looking to see if more of the seasoned web service veterans can comment on the best way to design a RESTful URI in where I need mandatory parameters. 我想看看是否有更多经验丰富的Web服务资深人士可以评论在我需要强制参数的地方设计RESTful URI的最佳方法。 Case in point, I'd like to design an URI that requests data:
举个例子,我想设计一个请求数据的URI:
example.com/request/distribution
However, from my understanding is that the approach is that more data should return at the higher levels while more detailed data would be returned if applying more specific URI keywords but in my case, I need at least 3 values for that to happen. 但是,根据我的理解,方法是更多数据应该返回更高级别,而如果应用更具体的URI关键字将返回更详细的数据,但在我的情况下,我需要至少3个值才能实现。 Those 3 values would be a date value, an account value and proprietary distribution code values.
这3个值将是日期值,帐户值和专有分发代码值。 For example:
例如:
example.com/request/distribution?acct=123&date=20030102&distcode=1A;1B;1C
Is that considered an "RESTful" URL or is there a better approach that would make more sense? 这被认为是一个“RESTful”URL还是有更好的方法更有意义? Any input is greatly appreciated.
任何输入都非常感谢。
BTW, Python is the language of choice. 顺便说一下,Python是首选语言。 Thanks!
谢谢!
URI's cannot, by definition, be "unRESTful" of themselves because the URI specification was guided by the REST architectural style. 根据定义,URI不能自己“unRESTful”,因为URI规范是由REST架构风格引导的。 How you use a URI can violate the REST style by:
如何使用 URI可能违反REST样式:
None of the above are necessarily bad choices . 以上都不一定是糟糕的选择 。 They might be the best choice for your system because they foster certain architectural properties (such as efficiency or security) .
它们可能是您系统的最佳选择,因为它们可以培养某些架构属性(例如效率或安全性)。 They're just not part of the REST style.
它们只是REST风格的一部分。
The fact that your resource is identified by multiple mandatory segments is part and parcel of the design of URI's. 您的资源由多个必需段标识的事实是URI设计的重要组成部分。 As Anton points out, the choice between
example.com/request/distribution?acct=123&date=20030102&distcode=1A;1B;1C
and, say, example.com/accounts/123/distributions/20030102/1A;1B;1C
is purely one of data design, and not a concern at the URI layer itself. 正如Anton指出的那样,在
example.com/request/distribution?acct=123&date=20030102&distcode=1A;1B;1C
和例如example.com/accounts/123/distributions/20030102/1A;1B;1C
; example.com/request/distribution?acct=123&date=20030102&distcode=1A;1B;1C
; example.com/accounts/123/distributions/20030102/1A;1B;1C
之间的选择纯粹是数据设计之一,而不是URI层本身的问题。 There is nothing wrong, for example, with responding to a PUT, POST, or DELETE request to the former. 例如,响应对前者的PUT,POST或DELETE请求没有任何错误。 A client which failed to follow a link to either one would be considered broken.
未能跟随任何一个链接的客户端将被视为已损坏。 A system which expected either one to be made available to the client by some means other than a hypermedia response would be considered "unRESTful".
期望通过除超媒体响应以外的某种方式使客户端可用的系统将被视为“不可靠”。
It's better to go about creating RESTful API in terms of resources first, not URIs. 最好先从资源方面创建RESTful API,而不是URI。 It has more to do with your data design than, say, with your language of choice.
它与您的数据设计有关,而不是与您选择的语言有关。
Eg, you have a Distribution resource. 例如,您有一个分发资源。 You want to represent it in your web-based API, so it needs to have an appropriate unique resource identifier (URI).
您希望在基于Web的API中表示它,因此它需要具有适当的唯一资源标识符(URI)。 It should be simple, readable, and unlikely to change.
它应该简单,可读,并且不太可能改变。 This would be a decent example:
这将是一个很好的例子:
http://example.com/api/distribution/<some_unique_id>
Think twice before putting more things and hierarchy into your URIs . 在将更多内容和层次结构放入URI之前,请三思而后行 。
You don't want to change your URIs as your data model or authentication scheme evolve. 随着数据模型或身份验证方案的发展,您不希望更改URI。 Changing URIs is uncool and pain for you and developers that use your API.
对于使用API的开发人员和开发人员来说,更改URI非常容易 。 So, if you need to pass authentication to the back-end, you probably should use GET parameters or HTTP headers (AWS S3 API, for example, allows both ).
因此,如果您需要将身份验证传递给后端,您可能应该使用GET参数或HTTP标头(例如,AWS S3 API 允许这两者 )。
Putting too much into GET parameters (eg, http://example.com/api/distribution/?id=<some_unique_id>
) may seem like a bad idea, but IMO it doesn't really matter[0]—as long as you keep your API documentation accessible and up-to-date. 过多地考虑GET参数(例如,
http://example.com/api/distribution/?id=<some_unique_id>
: http://example.com/api/distribution/?id=<some_unique_id>
)似乎是一个坏主意,但IMO并不重要[0] - 只要您可以访问API文档并获取最新信息。
[0] Update: For read-only APIs, at least. [0]更新:至少对于只读API。 For CRUD APIs, as @daniel has pointed out, it's more convenient when you have endpoints like in the first example above.
对于CRUD API,正如@daniel指出的那样,当您拥有上述第一个示例中的端点时,它会更方便。 That way you can nicely use HTTP methods by enabling GET, PUT, DELETE for individual resources at
/api/distribution/<id>
, and POST to /api/distribution
to create new distributions. 这样,您可以通过为
/api/distribution/<id>
各个资源启用GET,PUT,DELETE以及POST到/api/distribution
来创建新的发行版,从而很好地使用HTTP方法。
While researching the answer, found a nice presentation about RESTful APIs: Designing HTTP Interfaces and RESTful Web Services . 在研究答案时,发现了一个关于RESTful API的精彩演示: 设计HTTP接口和RESTful Web服务 。
RESTful方式是将数据表示为资源,而不是请求的参数:
example.com/distribution/123/20030102/1A;1B;1C
When you think about RESTful, most of the times you also should think about CRUD. 当你想到RESTful时,大多数时候你也应该考虑CRUD。
example.com/request/distribution?acct=123&date=20030102&distcode=1A;1B;1C
is fine for a GET-Request to show something (The R in CRUD). GET-Request可以显示某些内容(CRUD中的R)。
But what URLs do you consider for the CUD-Parts? 但是你对CUD-Parts考虑了哪些URL?
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.