[英]REST API same url - different response type
We are in process of designing a public exposed REST API. Trying to conform to industry standards ( https://restfulapi.net/ ) we came up to the following design questions:我们正在设计一个公开的 REST API。为了符合行业标准( https://restfulapi.net/ ),我们提出了以下设计问题:
[ { id: 1, code: 'I1' }, { id: 2, code: 'I2' }, { id: 3, code: 'I3' } ]
Along with this API, we got a requirement to support richer DTO as follows连同这个 API,我们得到了支持更丰富的 DTO 的要求,如下所示
[
{ id: 1, code: 'I1', name: 'Item1', Description: 'This is item1' },
{ id: 2, code: 'I2', name: 'Item2', Description: 'This is item2' },
{ id: 3, code: 'I3', name: 'Item3', Description: 'This is item3' }
]
How would you shape URL format (http:/.../..) richer response which has to be side-by-side with the simpler existing one?您将如何塑造 URL 格式 (http:/.../..) 必须与较简单的现有格式并存的更丰富的响应? Basically, we would like to have something like HTTP://www.mycompany.com/api/v1/items which is user-friendly format, stick to the standard, but again support multiple response formats.基本上,我们想要像 HTTP://www.mycompany.com/api/v1/items 这样的用户友好格式,坚持标准,但同样支持多种响应格式。 Keep in mind that we are hierarchically at the same level.请记住,我们在层次上处于同一级别。 Resource-naming is nicely explained here .资源命名在这里得到了很好的解释。
The forward-slash (/) character is used in the path portion of the URI to indicate a hierarchical relationship between resources.正斜杠 (/) 字符用于 URI 的路径部分以指示资源之间的层次关系。 eg例如
http://api.example.com/device-management http://api.example.com/device-management
http://api.example.com/device-management/managed-devices http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices/{id} http://api.example.com/device-management/managed-devices/{id}
http://api.example.com/device-management/managed-devices/{id}/scripts http://api.example.com/device-management/managed-devices/{id}/scripts
http://api.example.com/device-management/managed-devices/{id}/scripts/{id} http://api.example.com/device-management/managed-devices/{id}/scripts/{id}
//version 1 - alpha
class ItemService {
public void OrderItem(Item item)
{
if(item.ItemId == -1) //Create if doesn't exist
{
CreateItem();
}
}
}
//version 2 - beta
class ItemService {
public void OrderItem(Item item)
{
if(item.ItemId == -1) //Create if doesn't exist
{
CreateItem();
}
//Update if exist
else
{
UpdateItem(item);
SendEmail();
}
}
}```
Bottom line, our goal is to cover multiple API versions (alpha, beta...) fully supported with a backend that is also written in version-driven manner.
For your first problem I would see the richer DTO as the default that is returned for the regular URLs.对于您的第一个问题,我会将更丰富的 DTO 视为为常规 URL 返回的默认值。 Then add a query parameter to filter for the fields you want, if you need to strip out some of the fields.然后添加一个查询参数来过滤你想要的字段,如果你需要去掉一些字段。 (Like http://www.example.com/api/v1/items?fields=id,code ) (比如http://www.example.com/api/v1/items?fields=id,code )
If the query parameter is left out, the richer DTOs are fetched.如果省略查询参数,则会获取更丰富的 DTO。 If the default has to be the slim DTO it is also possible, but not as elegant or expandable.如果默认必须是 slim DTO,那也是可能的,但不是那么优雅或可扩展。
For the second problem I would recommend to develop each version of the API as individual deployable artifact.对于第二个问题,我建议将 API 的每个版本开发为单独的可部署工件。 Then deploy it with the version number as context (piece of the path somewhere at the beginning).然后使用版本号作为上下文(开头某处路径的一部分)进行部署。 This way you can fix bugs in older versions, undeploy older versions on demand individually without touching the other versions, and also add new versions without any hassle.通过这种方式,您可以修复旧版本中的错误,根据需要单独取消部署旧版本,而无需触及其他版本,还可以轻松添加新版本。
As REST interfaces should be stateless, these multiple versions in multiple deployables should not cause any extra problems.由于 REST 接口应该是无状态的,因此多个可部署文件中的这些多个版本不应引起任何额外的问题。
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.