3 ms·

Why not just use the OPTIONS verb? You're overloading verbs in order to make your API discoverable. Discoverability is great but there's a supported (and stand

Why not just use the OPTIONS verb? You're overloading verbs in order to make your API discoverable. Discoverability is great but there's a supported (and standard) way of accomplishing this already. Examples: GET /users {users: [{name: 'Bob'}, {name: 'Alice'}]} POST /users/create {name: 'Sally'} {name: 'Sally', id: '3'} OPTIONS /users {links: [{rel: 'userList', url: '/users'}, {rel: 'addUser', url: '/users/create', verb: 'POST'}]}

nbpoole 16y ago
To quote the blog post: "The reason for not supporting the DELETE/PUT methods is quite simple: by reducing the possible interactions to what a standard browser performs (GET/POST) we allow developers to interact with our api through their web browser." The same line of thinking applies to OPTIONS as well. Ideally, the API could support both types of usage, but that wasn't what they were trying to accomplish.
- hammerdr 16y ago
  I'm more questioning why they thought that was a good idea when there are some drawbacks to overloading GET and some known ways[1] to work around browser limitations of PUT/DELETE/OPTIONS on forms. For example, as a consumer of the API I would expect GET /clients to return a list of clients and not a OPTIONS-like response of possible paths. I'm definitely playing the purist here which is not my typical role. The OPTIONS solution is not a well known one but it is something that I'd like to be picked up. [1] http://guides.rubyonrails.org/form_helpers.html#how-do-forms-with-put-or-delete-methods-work http://guides.rubyonrails.org/form_helpers.html#how-do-forms...
  - qixxiq 16y ago
    The main reason at the end of the day is to land up with an API that is: a. Fully browse-able with standard web browsers. b. Acts in the exact same way with a browser as it does with any other client. The api design functions on the simple idea of having a "GET" request act as a discovery mechanism while "POST" requests perform operations and searches -- much like how most websites function. I understand you might expect the client listing at GET /clients, but I believe within a few minutes of looking at our design most people can work out its rather a POST /clients/list. You'll be looking at the documentation for almost any api you use, so I didn't really find that to be a major factor.
    - jsarch 16y ago
      FWIW, this comment: "The api design functions on the simple idea of having a "GET" request act as a discovery mechanism while "POST" requests perform operations and searches -- much like how most websites function." should make its way into your blog post or final documentation. I was thoroughly confused because there's no mention that GET and POST are actually different in the blog post. Best of luck with the API creation.
kaylarose 16y ago
I'd never heard of OPTIONS before. Do you have any links, besides [1], to more resource on it? Is this a common tactic, or is there a more standard way to add "discover-ability" to REST apis? I usually try to mimic this kind of functionality with something like this [2]. But it always seems kludgy. [1] http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html [2] http://gemdash.tumblr.com/post/2798389935/restful-api-design http://gemdash.tumblr.com/post/2798389935/restful-api-design [Half-assed attempt at an blog post]

nbpoole 16y ago

To quote the blog post: "The reason for not supporting the DELETE/PUT methods is quite simple: by reducing the possible interactions to what a standard browser performs (GET/POST) we allow developers to interact with our api through their web browser." The same line of thinking applies to OPTIONS as well. Ideally, the API could support both types of usage, but that wasn't what they were trying to accomplish.

hammerdr 16y ago
I'm more questioning why they thought that was a good idea when there are some drawbacks to overloading GET and some known ways[1] to work around browser limitations of PUT/DELETE/OPTIONS on forms. For example, as a consumer of the API I would expect GET /clients to return a list of clients and not a OPTIONS-like response of possible paths. I'm definitely playing the purist here which is not my typical role. The OPTIONS solution is not a well known one but it is something that I'd like to be picked up. [1] http://guides.rubyonrails.org/form_helpers.html#how-do-forms-with-put-or-delete-methods-work http://guides.rubyonrails.org/form_helpers.html#how-do-forms...
- qixxiq 16y ago
  The main reason at the end of the day is to land up with an API that is: a. Fully browse-able with standard web browsers. b. Acts in the exact same way with a browser as it does with any other client. The api design functions on the simple idea of having a "GET" request act as a discovery mechanism while "POST" requests perform operations and searches -- much like how most websites function. I understand you might expect the client listing at GET /clients, but I believe within a few minutes of looking at our design most people can work out its rather a POST /clients/list. You'll be looking at the documentation for almost any api you use, so I didn't really find that to be a major factor.
  - jsarch 16y ago
    FWIW, this comment: "The api design functions on the simple idea of having a "GET" request act as a discovery mechanism while "POST" requests perform operations and searches -- much like how most websites function." should make its way into your blog post or final documentation. I was thoroughly confused because there's no mention that GET and POST are actually different in the blog post. Best of luck with the API creation.

kaylarose 16y ago

I'd never heard of OPTIONS before. Do you have any links, besides [1], to more resource on it? Is this a common tactic, or is there a more standard way to add "discover-ability" to REST apis? I usually try to mimic this kind of functionality with something like this [2]. But it always seems kludgy. [1] http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html [2] http://gemdash.tumblr.com/post/2798389935/restful-api-design http://gemdash.tumblr.com/post/2798389935/restful-api-design [Half-assed attempt at an blog post]