CODEWITHSUNDEEP
restrestful-url
SingleShot
SingleShot

Reputation: 19131

How Would You Design a RESTful Conversion Service?

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?

Upvotes: 1

Views: 1737

Answers (1)

manuel aldana
manuel aldana

Reputation: 16458

I would suggest using parameters and GET. I also would switch path elements and make /conversions your root-resource, as conversion is your "domain-core".

Main reasons are:

  • From api-client perspective above is easier to use (no POST payload, very easy to test/try-out). Client friendliness is one of the highest priorities for api-design.
  • GET fits better because you don't "change" anything on the server side but rather convert things.
GET /conversions/coordinate?input=xxx&format=yyy

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)?

Upvotes: 3

Related Questions