Hope this helps.GET /conversion/EUR/CNY/100
-Mike
--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group, send email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
If you read the relevant section in the ebook again, I think you will see what my real question was.
Okay, I just read page 19 and see what you were referring to, I guess I misread your post. Sorry.That said, I can't say that the recommendations on that page make any sense to me either. I think it's bad form to build an API based on how it's implemented in the back end; the API should be designed from the perspective of the user of the API. I also don't think there are many (any?) cases where verbs sense to identify resources.
Thanks for your reply Glenn,
Who says the noun has map 1 to 1 to the database? I don't think that is true at all.
The book that I was referring to says that (it is also available as a video on youtube: http://youtu.be/QpAhXa12xvU )
You can absolutely have resources which are not backed by any database or even any persistence mechanism. For example you can have a Calculator resource that is completely stateless and idempotent. You do a GET to it passing some information like this http://calculation.com/calculator/add/2+3 (no this does not exist) and it returns the result. The result never changes so it is cachable.The main thing about using nouns as resources is it naturally fits with the uniform interface. I can check up on a thing (GET), I can add a thing (POST), I can replace a thing (PUT) and I can remove it (DELETE). 'Thing' here means noun. Now not everything supports all methods as in the example I just posted, that resource only supports GET. But that is also fine as I am not violating any thing from an HTTP perspective.
Sorry, I think you missed the point. According to the book (and I think the author is right here), the example you just gave is the reason why verbs should be used in APIs. Probably the majority of the developers will know, when they look at an API endpoint like: /calculator/add that the call will give back an error if they were to use POST, PUT or DELETE. Because it just doesn't make sense to do that. You are not deleting / updating / storing something that you could later query for example. If they were meaningful, then you would immediately come to realise that you have something that is actually being stored on the API's side. So then you should be using nouns, therefore you end up having a true resource. That's why the book suggests, that everytime you have a call like yours, (let's call it now /calculate, with a verb) then that should be separate from the rest of your calls. And if people start using verbs based on this idea, then developers can (maybe in the future) already have pre-assumptions when looking at API calls with verbs: "Oh, this is a verb, then this is some non-resource-y call, that just calculates / does something and doesn't modify my stuff on the API's side."In terms of 'actions' behind each action there is a noun waiting to be discovered. The examplez I use (overuse) is contact management. Let's say I have a contact resource. Now I want to support the ability for contacts to connect, so I can say 'Glenn connects to Steve'. Connect is a verb, but I can flip things around and say contacts have connections, and there you go, my connections resource is born. I can now post 'Steve' to '/contacts/glenn/connections'. The uniform interface comes in nicely here because I can get connections, add connections, remove connections.Yes, I think this is the point. "behind every action, there is a noun waiting to be discovered". Every action on a resource will in some way result in a DB read or write. Which is why Foursquare's API looks kind of flawed.This is how venues and likes operate on Foursquare (https://developer.foursquare.com/docs/venues/likes, https://developer.foursquare.com/docs/venues/like)POST /v2/venues/:id/like?set=0 // unlikePOST /v2/venues/:id/like?set=1 // likeGET /v2/venues/:id/likes // returns who liked the venueApart from the fact that they don't use DELETE for unliking (which might be better for developers, because the API becomes easier to test this way) they use a different resource for querying likes (notice the difference between "like" and "likes"). Instead of acting on the related resource (using POST, PUT, DELETE, GET) they rather introduce verbs. And I think this is the key point. Whenever you want to do actions (other than CRUD) on resources, there is always a corresponding resource that you can act on. And by specifying it in a "resouce/identifier/resource" fashion, you will no longer need to add verbs.(I've been thinking a lot about this, and didn't think we would find this answer this quickly, thanks Glenn)
On Sep 29, 2012, at 2:57 PM, Kristof Kotai <> wrote:
Hi everyone,just wanted to give my feedback on this book: http://offers.apigee.com/api-design-ebook-rr (since the author mentioned that we can post feedback here, I'll do so...). I actually have more questions, but I'll just start with one so that we can focus on them one-by-one...So the first thing I wanted to ask is about the use of verbs and nouns in the URIs. The ebook seems to advise developers to make a clear distinction between calls that are named using verbs (calls that don't work on resources, which rather make some sort of calculation / conversion / translation that don't involve resources being returned) and resources, that map to something in the database for example. Using an example from the ebook:GET /convert?from=EUR&to=CNY&amount=100Sure, I understand that in this case this is the best way to name the URI, but in general? Why would it be. I mean, verbs are the only way to describe actions. And sometimes you have to make actions (other than CRUD) on resources... Obviously you can not invent new HTTP methods for that purpose, so you have to add verbs somehow. The ebook refers a lot to Foursquare's API (and it approves of that as well), but looking at their API, that quite contradicts what the author says. For example:"addcomment" is a verb, and no it is not a clearly separated call, the resource name is still there as a prefix. So would the following be the right solution then?I think Foursquare's approach is spot on, but then why does the author say the complete opposite? That if you use verbs, don't mix it with existing resource names, and you should somehow indicate in the API docs that these calls are separate from the rest of the resource-based calls.Thanks, Kristof--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group, send email to api-craft+unsubscribe@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group, send email to api-craft+unsubscribe@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group, send email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
--
It's my belief that we need to embrace behaviors in our Web APIs. We can do this like so:POST /customers/123message=deactivate&reason=delinquentThis is comparable to an object receiving a message and is similar to how some programming languages interpret a method call.
How are those RPC? That's state transfer of a resource with the intent expressed through the method. RPC is GetListOfUsers, PostOrders, DeleteWorldHunger. In that case the intent is expressed through the URI, it it is being used to express a method call on an object.
OO also talks about inheritance, would you say we should be having resources that inherit form one another? Do we have resources with virtual methods?
--
What does the business need? (which includes things like evolvability, etc)What does the user need?How can the business deliver on both?
Those are the questions that matter!
At the risk of empowering "the narcissism of small differences"[1] can we talk about Nouns and Verbs? I'm channelling my 11th grade English teacher on this one and I agree with Kristof, having well established guidelines can be really helpful at times.
Can a present a strawman argument for why I think nouns make more sense for (partially) RESTful web-based APIs and then ask for others to challenge and/or support these arguments??
Is an action like "convert" an entity? Does it make sense that you'd want your resource to return a representation with information about an entity identified by the name "convert?" Or would it make more sense to return information about a conversion? From those three it seems to me that verbs would be unnatural choices to identify a resource.1.) REST requires a uniform interface, and as I understand it the uniform interface for HTTP[2] include the four verbs GET, POST, PUT and DELETE. Correct? Incorrect? Supporting references?2.) A key abstraction in REST is the "resource"[4] and a resource is a conceptual mapping to an entity (or set of entities.) Resources have identifiers (i.e. URIs) that identify some concept, even if that concept changes over time. Correct? Incorrect? Supporting references?3.) "REST components perform actions on a resource by using a representation to capture the current or intended state of that resource and transferring that representation between components."[5]
If you make the following HTTP request then isn't the representation returned information about the conversion and not about the convert (verb being used as noun here?) Correct? Incorrect? Supporting references?
GET /convert?from=EUR&to=CNY&amount=100 HTTP/1.1
I can see the argument that the entire URL including the query params represents the conversion, but isn't that more rationalizing than modeling? Maybe I'm wrong but if so I can't see it yet. Help me see it?
I guess I'm trying to ask you to ask yourself this:
"Can the name you've given your URL be applied to the representation of the resource when you do a GET on it, or is the representation the result of some action taken and not about the resource itself?" If it's the latter, isn't the resource poorly named?(And yes, I know URLs are "opaque" and can be meaningless but that doesn't mean we don't need to apply a named concept to them when we are architecting them. We are talking about the name you give the URL and the name you use to document the URL, even if the text of then URL itself doesn't contain meaning.)
Remembering #1 from above, that REST's uniform interface is a set of *verbs*. Does it make sense to use this construct?
{VERB} /{verb} HTTP/1.1
Or isn't this more clear?
{VERB} /{noun} HTTP/1.1
Am I really being too pedantic here? I don't know, let me know if I am.Ignoring all that, let's look at the RESTful properties of GET, POST, PUT and DELETE:
Does a verb like "convert" imply a safe operation? If I convert something, haven't I caused a "side effect?""The GET method must be a safe method (or nullipotent) meaning that calling it produces no side-effects."[6]"The PUT and DELETE methods much be idempotent methods meaning that multiple identical requests should have the same effect as a single request"[7]
Should I be able to cache an "action", or does it make more sense to cache the "result" on an action (or simply re-imagine it as an entity that can be cached?)
Further RESTful HTTP assumes that you can apply each of the different verbs GET, POST, PUT and DELETE to the same URL and it would behave as appropriately expected (ignoring that resources can fail process a given HTTP verb and that's okay too.) So let's consider this:
GET /convert?...Or does this seem like it makes more sense:
PUT /convert?... (what are we updating?)
DELETE /convert?... (are we removing the ability to convert from the API?)
GET /conversion?...
PUT /conversion (we are updating the conversion because the exchange rate has changed?)
DELETE /conversion (we are done with it and the system can forget it.)Yes, the previous is probably picking nits. But taken all together, is all of it really picking nits, or does all of this combine contribute to recommending nouns and recommending against verbs?As a follow up I think my suggestion to model as "conversion" was not well considered. I'm now thinking a "conversion" resource doesn't make sense and instead what does is an exchange rate resource. The client can easily do the math to multiple the exchange rate times the amount; you don't need a web service to multiple a number do you?
GET /exchange-rate/EUR/CNY (get the current exchange rate for EUR->CNY)GET /exchange-rate/CNY/EUR (get the current exchange rate for CNY->EUR)PUT /exchange-rate/EUR/CNY (update to a new exchange rate for EUR->CNY)
PUT /exchange-rate/CNY/EUR (update to a new exchange rate for CNY->EUR)DELETE /exchange-rate/EUR/CNY (remove exchange rate information for EUR->CNY)
DELETE /exchange-rate/CNY/EUR (remove exchange rate information for CNY->EUR)
This also works nicely if you want to get historical information:
GET /exchange-rate/EUR/CNY/2012-01-01 (get exchange rate for EUR->CNY from Jan 1 2012)GET /exchange-rate/CNY/EUR/2012-01-01 (get exchange rate for CNY->EUR from Jan 1 2012)
As a final aside, some people suggested that a URL might inappropriately imply a point in time. For this I'll lean on Roy again[4]:
A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.
...
Some resources are static in the sense that, when examined at any time after their creation, they always correspond to the same value set. Others have a high degree of variance in their value over time.
...For example, the "authors' preferred version" of an academic paper is a mapping whose value changes over time, whereas a mapping to "the paper published in the proceedings of conference X" is static. These are two distinct resources, even if they both map to the same value at some point in time. The distinction is necessary so that both resources can be identified and referenced independently.This abstract definition of a resource enables key features of the Web architecture. ... Finally, it allows an author to reference the concept rather than some singular representation of that concept, thus removing the need to change all existing links whenever the representation changes (assuming the author used the right identifier).... The naming authority that assigned the resource identifier, making it possible to reference the resource, is responsible for maintaining the semantic validity of the mapping over time (i.e., ensuring that the membership function does not change).
All this together tells me that whenever someone presents a verb for a resource it means they probably haven't done enough analysis to discover the noun. However I would like to know if others on this list find these arguments compelling, or if you have conflicting opinions and if so why? Maybe I've just missed something key thus far?