1

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?

1 Answer 1

3

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

3
  • Thanks. No, there is no server state. I think I prefer your way of looking at it. I'll wait and see what others ideas pop up before accepting.
    – SingleShot
    Aug 17, 2011 at 20:30
  • how would I achieve something similar if the input is a file/stream that should be converted?
    – fra
    Feb 7, 2017 at 8:19
  • @manuel-aldana, I also think GET is more appropriate action here as conversion doesn't change anything on server. However, there're cases when you want to convert a bigger object, that's not appropriate to put (big json blob) in query param. Then there's a long discussion on swagger-ui, github.com/swagger-api/swagger-ui/issues/2136, and the final verdict is GET doesn't support payload in body. What's your thought? Would you use POST instead?
    – chepukha
    Mar 10, 2020 at 8:07

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.