我应该在 URL 中提供父资源名称还是在 RESTful WS 中不提供? [英] Should I provide parent resource name in URL or not in RESTful WS?

问题描述

我正在使用 PHP 和 apache 开发一些基本的 Restful Web 服务，我想知道是否应该构建提供父实体名称的 URL.让我更好地解释一下:

我有 2 个实体，假设国家和城市.我现在只提供 WS 来获取、创建、更新或删除城市，但 API 不支持通过 WS 操作国家.我正在使用 mod_rewrite 重新映射 url，并且我在 api 中提供以下 url 来操纵城市:

<预><代码>.GET/api/countries//cities id为的国家/地区的城市.GET/api/countries//cities/id为的城市.POST/api/countries//cities 向国家/地区添加一个城市，id 为 ;.PUT/api/countries//cities/;更新其国家/地区 ID 为 的城市；.删除/api/countries//cities/;删除城市...

我开始仔细查看这些 url，但我对是否应该提供父实体名称和 ID 感到困惑.我做了一个很好的假设，城市不能分配给多个国家，即它不是多对多的关系.假设这一点，我认为可以为许多 API 函数提供更短的 URL 模式.例如，如果客户想删除某个城市，他发送:

<预><代码>.删除/api/cities/14

我知道一个城市属于一个国家，客户端在提出请求之前不需要找出国家ID.

除了第一个(获取所有国家的城市)外，大多数 url 都可以转换为这种较短的 url.

这是我第一次开发 Web 服务，我没有阅读太多关于它的内容，所以我可能会误解一些东西.我能得到一些建议吗?非常感谢，也很抱歉我的英语水平太差.

我认为这个问题可以概括为我应该如何处理 API url 中的实体关系?"

解决方案

'我应该如何处理 API url 中的实体关系?别.而是在您回复的资源中使用链接.

例如，如果我在 /cities/612 上执行 GET，我可能会返回

{ '城市':{'id':612，'自我':'/城市/612'，'name': '悉尼','国家':{'名称':'澳大利亚'，'href':'/国家/61'}，'region': { 'name': '亚太地区', 'href': '/region/12' },'删除': {'方法':'删除'，'href':'/城市/612'},'更新': {'方法':'放置'，'href': '/城市/612',...},...}}

这允许您拥有任何您喜欢的实体关系，而不必担心您的 URL.您还可以轻松添加新关系，而不会破坏现有客户.例如，如果您想添加一个新的 'planet' 关系，/cities/612 上的 GET 现在可能会提供

{ '城市':{'id':612，'自我':'/城市/612'，'name': '悉尼','国家':{'名称':'澳大利亚'，'href':'/国家/61'}，'region': { 'name': '亚太地区', 'href': '/region/12' },'行星':{'名称':'地球'，'href':'/行星/1'}，'删除': {'方法':'删除'，'href':'/城市/612'},'更新': {'方法':'放置'，'href': '/城市/612',...},...}}

查看三个简单步骤的 RESTful 超媒体 API，了解更多详细信息.

I am developing some basic restful web services using PHP and apache and I am wondering whether I should build the URLs providing the parent entity name or not. Let me explain this better:

I have 2 entities, lets suppose countries and cities. I am now just providing WS to get, create, update or delete cities but the API won't support countries manipulation via WS. I am remapping urls using mod_rewrite and I am providing the following urls in the api to manipulate cities:

. GET     /api/countries/<country_id>/cities            cities of country with id <country_id>

. GET     /api/countries/<country_id>/cities/<city_id>  city with id <city_id>

. POST    /api/countries/<country_id>/cities            add a city to country with id <country_id>

. PUT     /api/countries/<country_id>/cities/<city_id>  update the city whose country has id <country_id>

. DELETE  /api/countries/<country_id>/cities/<city_id>  delete city ...

I started looking careful at these urls and I got confused whether one should provide the parent entity name and id or not. I am making a great assumption and is that cities cannot be assigned to more than one country, i.e. it is not a many-to-many relationship. Assuming this I think a shorter URL pattern could be provided for many of the API functions. For example if the client wants to delete some city it would be enough if he send:

. DELETE /api/cities/14

I know that a city belongs to one country, and the client does not need to find out the country id before making the request.

The majority of the urls can be transformed into this shorter kind of url except for the first one (get all countrie's cities).

This is my first time developing web services and I haven't read too much about it so I may be probably misunderstanding something. Can I please get some advice? Thanks a lot and sorry for my rudimentary english.

EDIT1: I think the question can be generalized in 'How should I handle entities relationship in API urls?'

解决方案

'How should I handle entities relationship in API urls?' Don't. Instead use links in the resources you respond with.

For instance, if I do a GET on /cities/612 I might get back

{ 'city': 
  {
    'id': 612,
    'self': '/cities/612',
    'name': 'Sydney',
    'country': { 'name': 'Australia', 'href': '/country/61' },
    'region': { 'name': 'Asia Pacific', 'href': '/region/12' },
    'delete': {
      'method': 'delete',
      'href': '/cities/612'
    },
    'update': {
      'method': 'put',
      'href': '/cities/612',
        ...
    },
    ...
  }
}

This allows you to have any entity relationship you like, without having to worry about your URLs. You can alos easily add new relationships without breaking existing clients. For instance, if you wanted to add a new relationship of 'planet', GET on /cities/612 might now provide

{ 'city': 
  {
    'id': 612,
    'self': '/cities/612',
    'name': 'Sydney',
    'country': { 'name': 'Australia', 'href': '/country/61' },
    'region': { 'name': 'Asia Pacific', 'href': '/region/12' },
    'planet': { 'name': 'Earth', 'href': '/planet/1' },
    'delete': {
      'method': 'delete',
      'href': '/cities/612'
    },
    'update': {
      'method': 'put',
      'href': '/cities/612',
        ...
    },
    ...
  }
}

Have a look at A RESTful Hypermedia API in Three Easy Steps for more details.

这篇关于我应该在 URL 中提供父资源名称还是在 RESTful WS 中不提供?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！