Summary: | ASTERISK-22737: Rename ARI Playback to Playbacks | ||
Reporter: | Paul Belanger (pabelanger) | Labels: | |
Date Opened: | 2013-10-20 21:35:34 | Date Closed: | 2013-11-08 11:41:27.000-0600 |
Priority: | Major | Regression? | |
Status: | Closed/Complete | Components: | |
Versions: | 12.0.0-beta1 | Frequency of Occurrence | |
Related Issues: | |||
Environment: | Attachments: | ||
Description: | Currently playback is the only resource not plural. For consistency it should be renamed to playbacks | ||
Comments: | By: Matt Jordan (mjordan) 2013-10-21 08:33:15.554-0500 I don't agree. The other resources are plural because they describe multiple things. Playback as a resource does not: it only describes a single playback operation. Implying that a playback resource describes all existing playback operations on all channels feels wrong. By: Matt Jordan (mjordan) 2013-10-21 08:33:49.572-0500 Also: we should probably discuss things that are not obvious bugs on the asterisk-app-dev mailing list before making issues. By: Leif Madsen (lmadsen) 2013-10-22 08:20:47.036-0500 Per restapitutorial.com: {quote} Let's talk about the debate between the pluralizers and the "singularizers"... Haven't heard of that debate? It does exist. Essentially, it boils down to this question... Should URI nodes in your hierarchy be named using singular or plural nouns? For example, should your URI for retrieving a representation of a customer resource look like this: GET http://www.example.com/customer/33245 or: GET http://www.example.com/customers/33245 There are good arguments on both sides, but the commonly-accepted practice is to always use plurals in node names to keep your API URIs consistent across all HTTP methods. The reasoning is based on the concept that customers are a collection within the service suite and the ID (e.g. 33245) refers to one of those customers in the collection. Using this rule, an example multi-node URI using pluralization would look like (emphasis added): GET http://www.example.com/customers/33245/orders/8769/lineitems/1 with 'customers', 'orders', and 'lineitems' URI nodes all being their plural forms. This implies that you only really need two base URLs for each root resource. One for creation of the resource within a collection and the second for reading, updating and deleting the resource by its identifier. For example the creation case, using customers as the example, is handled by the following URL: POST http://www.example.com/customers And the read, update and delete cases are handled by the following: GET|PUT|DELETE http://www.example.com/customers/{id} As mentioned earlier, there may be multiple URIs for a given resource, but as a minimum full CRUD capabilities are aptly handled with two simple URIs. You ask if there is a case where pluralization doesn't make sense. Well, yes, in fact there is. When there isn't a collection concept in play. In other words, it's acceptable to use a singularized resource name when there can only be one of the resource—it's a singleton resource. For example, if there was a single, overarching configuration resource, you might use a singularized noun to represent that: GET|PUT|DELETE http://www.example.com/configuration Note the lack of a configuration ID and usage of POST verb. And say that there was only one configuration per customer, then the URL might be: GET|PUT|DELETE http://www.example.com/customers/12345/configuration Again, no ID for the configuration and no POST verb usage. Although, I'm sure that in both of these cases POST usage might be argued to be valid. Well... OK. {quote} By: Matt Jordan (mjordan) 2013-10-22 09:32:33.106-0500 Thanks for the well reasoned, cogent reply Leif :-) Works for me. Paul: want to provide a patch that renames the resource? |