We are creating a service to perform conversions from one format to another. Examples of conversions are currencies, distances, times, languages, etc. In our case it is geographic points (for example from decimal degrees latitude/longitude to degrees-minutes-seconds latitude/longitude).
Typically a RESTful resource has an analogous OO concept that is persistent on the server side that can be CRUDed (I know this is only part of what makes something RESTful), but in the case of a simple service that converts things, that doesn’t necessarily exist. How would one make this RESTful? Currently we have some like this:
To get the list of supported formats one can do this:
GET /coordinates/formats
Which would return a list of formats, including, for example DD and DMS (decimal degrees and degrees-minutes-seconds).
One can then turn around and perform a conversion like so:
POST /coordinates/DD/as/DMS
In this example one would pass a representation of decimal degrees (as JSON or some other format) in the request body, and receive a representation of degrees-minutes-seconds in the response body.
This of course works, but feels unRESTful, in particular because the same URI is used over and over for different inputs (different decimal degrees). The trick is probably to really concentrate on what the resource being manipulated it. Perhaps its a “Conversion”:
POST /coordinate/conversions
The body might take in the a value, its format, and the desired output. However, the URI is still the same for all resources…
Thoughts?
I would suggest using parameters and
GET. I also would switch path elements and make/conversionsyour root-resource, as conversion is your “domain-core”.Main reasons are:
I like your approach to give back metadata with
/conversions/formats. It makes formats easy to lookup and your api more self-explainable. The respective data then forms the possible value for ‘format’-parameter from above call.Or are you storing conversion (which would favor state-changing POST method)?