Embedded files in an api response

[Sebastien Auroux]

hello

some api returns files in the response. some vendors choose to have an url than points to an external file, and some others choose to embed the file in binary directly in the response. I am wondering how the api developpers choose one way or the other. Lets take an example, for imagery maps, esri (a mapping module provider) choose sometimes to embed the file in the response, but the google maps imagery is always a external url.

is there a best pratice ?

thanks

[Repenning, Jack]

On May 15, 2013, at 8:09 AM, Sebastien Auroux <minis...@gmail.com> wrote:

some api returns files in the response. some vendors choose to have an url than points to an external file, and some others choose to embed the file in binary directly in the response. ...

is there a best pratice ?

I don't think there is any universal "one right answer." You should be guided by what you expect your users to do next, in general.

For example, if you're implementing an API function that means "fetch this file based on these search criteria, like

  GET /api/file?q="big red octagonal sign with STOP written on it"

it would be silly to return merely an URL to a picture of a stop sign. The caller *asked* for the file, send the file!

OTOH, if you're implementing an API function that returns a more complex resource, and some or even most "likely next steps" do not involve fetching the file, then return the URL. 

For example, if you're implementing an AP function that means "fetch the user profile," the next step might be to display the user's avatar image ... but then again, it might be to dial the home phone number, or send a package to the snail-mail address, or several other "next steps". In this case, saving the net.bandwidth of delivering the file is more attractive.

Your case is probably less obvious than either of those (I tried to pick extremes), but the point is to ask "what will the caller do next?"

-- 

Jack Repenning

Repenni...@gmail.com

[Sebastien Auroux]

thank you for your answer, it makes sense.