(Using URL templates is a potentially simpler way to achieve the same thing). This is, of course, your solution 2.
There are tradeoffs involved in using this style. Are they worth it? That really depends on the larger system and all kinds of details which you've left out.
That is not a RESTful solution, though: what resource is it acting on? What are the four CRUD operations for it?
You have to come up with some added, unnecessary, implementation-exposing abstraction like "CityPair". (In which case "delete" could be ill-defined if, as would be wise, the distance is computed from a lat/long or road table lookup, and so there is no actual database entry that corresponds to the distance between the cities.) That's the problem with REST: it doesn't avoid the complexity of RPC; it just crams it into ever-more-creative resource types.
Most API users (sorry, "consumers") would prefer they just be told the format in which to ask for the data, not have to re-discover it through gradually-exposed paths each time.
Don't be cute. What server resource is it acting on? The value of the distances is (potentially) computed by some encapsulated algorithm -- you're not acting on that resource. The server resources that are touched are the two cities, and then whatever it does behind the scenes.
>This is a really weird thing to say. No, you don't. I have no idea why you would think that.
Because I'm not GETing a city, so I can't use the GET operation on the city resource; I have to make another resource to GET. Fine, it doesn't have to be a city pair: but there is a many-to-many mapping, which in REST-favoring frameworks (e.g. Rails), requires a separate table. By reducing everything to CRUD, you must create a new resource (type) for each new operation.
>(And POST/GET/PUT/DELETE is a very different concept from CRUD.)
That's a non-standard definition of "very different", considering that POST is create, GET is retrieve, PUT is update, and DELETE is delete.
Yep! Works like a charm, until you have to expose a URI pointing to every combination of cities (or indeed, combination of any parameter set).
And I know (like I said before) you can fall back on "no, just tell the user where to put the parameters and you won't have to do that!" ... which is just re-inventing the RPC -- and satisfying users that don't want to navigate a long session just to find the URI they want, every time they send a request.
>Also, while POST can mean "create", it can also mean "append" or "process some arbitrary request."
Used correctly, it doesn't mean (that the sender is requesting that you) "process some arbitrary request"; it should only be used for non-idempotent operations. Close enough to summarize as "create" (appending is certainly creating something in this context!), and generally, for something to have different effects when repeated, you have to create something. PUT/update and DELETE/delete are idempotent specifically because the changes they make aren't creations.
In any case it's clearly an abuse of the term "very different concept from" in the GGP's comment "And POST/GET/PUT/DELETE is a very different concept from CRUD".
> 2. instruct clients on how to construct appropriate URIs
> 3. link a URI for the starting city and then from there link them to possible choices of the second city
All three of these are possible RESTful solutions, and I can imagine situations where each of them might make sense.
But what you're probably looking for is something like this:
(Using URL templates is a potentially simpler way to achieve the same thing). This is, of course, your solution 2.There are tradeoffs involved in using this style. Are they worth it? That really depends on the larger system and all kinds of details which you've left out.