RESTful API discussing resources - image downloads

Question

My question is very simple, i am designing an Aplication(In Ruby on Rails BTW) that will also have a RESTful API to it.

During the design of the application I came into the problem of what is a resource in: "download an image".

I found 2 options:

1. Have a controller named ImagesController and a show action that actually returns the file to be downloaded.(GET request)

2. Have a controller named ImageDownloadsController and a create action!(POST request)

The reason why I choose the second one is because for me a show action of images controller would make more sense to return the image url to be shown on the browser or the template with the image already.

Also because when I design the API, I think it will be easier and make more sense that it matches the most of my application. What I mean is that the API is faithful to what I designed on my APP. So that the controller actions on the API matches most of the ones on the APP.

I think it can be a problem for the sake of design that my APP on ImagesController#show returns a file and that on my API it returns an URL.

Instead I would like to have on my APP a controller called ImageDownloadsController where create returns the file. And on my API a ImagesController where show returns the url! I still dont like the name ImageDownload for a resource!

I would like to hear your thoughts on this, and why do you think one option is better than the other if possible.

Answer 1

From an expectation perspective, if I were to blindly (without RTM) develop a client I would expect to GET an image if I used that verb using your REST API, because that is how it is commonly used.

Now in your case you want to deviate from it so it matches your app controller. Well that is fine, especially if you are the only one who will consume the REST API service, but if other people will develop clients for it then I would choose for your first solution if you want to use the REST approach consistently.

Answer 2

I think it depends on who will use your API.

• If your API will be used by your internal team, then go with the solution that is more testable and consistent with your application architecture.
• If your API will be public, then you should consider your API as "GUI for developers" and make it as usable as possible. One of the best ways to achieve that is to conduct usability studies - i.e. ask different developers who are absolutely new to your API what method they expect to use for downloading images.

BTW, I agree with Kay Tsar - if I downloaded an image I would use the "GET" method.