search

libopenstorage / openstorage

A multi-host clustered implementation of the open storage specification
Apache License 2.0
525 stars 118 forks source link

trailing / in API specification should be removed #186

Open paravmellanox opened 7 years ago

paravmellanox commented 7 years ago

I like to fix the API specification for following functionalities in http://api.openstorage.org. All of them have trailing / after {uuid} as {uuid}/.

  1. Delete Volume
  2. Inspect Volume
  3. Change Volume state
  4. Retrieve Volume *

In general most REST services /resource/ indicates set of resources. Here in above methods, interest is particular volume described by uuid. So trailing / is confusing, which should be removed.

There are few good examples describing why trailing slash confuses and should be avoided while describing a specific resource. (1) http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#restful (2) Applied Web Services section in https://en.wikipedia.org/wiki/Representational_state_transfer#Example (3) https://softwareengineering.stackexchange.com/questions/186959/trailing-slash-in-restful-api

Who are the author of the http://api.openstorage.org? As this is more of documentation bug, I like to contact the author(s).

jvinod commented 7 years ago

Thanks @paravmellanox for pointing this out. The best would be to submit a PR against https://github.com/libopenstorage/specs/blob/master/api/openstorage.yaml. ping @brianhama

venkatpx commented 6 years ago

@pault84 pls follow up on this.