Recognizing a method by URI

[Oldemiro Americo Baloi]

Hello Everyone,

It can looks like a dumb question, I am learning about REST, HATEOAS and more for my api, I curious to know I can I know if a URI request is which kind type of verb,

eg. in PAYPAL we have /execute which means a post and I can handle it has a post.

https://api.sandbox.paypal.com/v1/payments/payment/PAY-24V60973YB7819112KV5UXNA/execute

[Jack Repenning]

On Jun 12, 2015, at 2:30 PM, Oldemiro Americo Baloi <oldemir...@gmail.com> wrote:

It can looks like a dumb question, I am learning about REST, HATEOAS and more for my api, I curious to know I can I know if a URI request is which kind type of verb,

eg. in PAYPAL we have /execute which means a post and I can handle it has a post.

You can't tell from the URI which method it takes. In fact, it's common to use the same URI with different verbs, to mean different things. For example:

GET /dogs/37      - retrieves info about dog #37

DELETE /dogs/37 - removes doc #37 from the database

-- 
Jack Repenning
Repenni...@gmail.com

[Chris Mullins]

This doesn't really answer your question, but OData (a fairly robust set of REST API standards used in a number of Enterprise scenarios) defines Actions and Functions and is pretty deeply thought through. 

To execute an Action one would POST to the action. 

There is an interesting overview of them here. Stealing from that article:

From OData V4 spec, functions and actions both are operations and can be either bound to a type or unbound. However, there's a little bit difference between them:

• Functions are operations that do not have side effects, may support further composition and must have return type.
• Actions are operations that allow side effects, such as data modification, and cannot be further composed in order to avoid non-deterministic behavior.

One interesting upside of the OData approach is the metadata language that can be queried to determine the list of functions / actions. 

Cheers,

Chris

[mca]

1) the most scale-able approach to communicating what method to use for a URL is a control in the message.HTML uses FORMs for this. Siren uses "actions", Cj uses "template"

2) the next level down from that scale is to write it all up in human-readable documentation and tie that documentation to the URL directly via a REL value. HAL uses this approach.

3) further down on the spectrum is to write it up in human-readable docs w/o any direct connection in the response. most CRUD-style apps use this approach today.

4) a less-scale-able approach is to do what you mention at the top of this thread, create a local convention based on characters in the URL itself. this requires reading the docs AND associating those docs with the URL via a code implementation. I don't see many doing this IRL

5) finally, you can do what the WSDL/Web Services folks did. make ALL URLs support a single method (POST) and be done w/ it. this ignores lots of HTTP value (like caching) but has the advantage of being very human-friendly (you don't need to decided anything) and easy to implement using code-generation (all operations are the "same").

there might be some other levels in there that i've missed but that's the spectrum i've seen IRL as a visit dozens of companies around the world.

FWIW, i advocate using option 1 as often as possible.

cheers.

mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Chris Mullins]

This is a really great answer. 

-- Chris

[sgoto]

+1 what Mike said.

FWIW, (1) is what we ended up in schema.org actions too:

http://schema.org/EntryPoint

--

f u cn rd ths u cn b a gd prgmr !