[seagrant-dev] Remaining API questions

[Kennric]

The main remaining question I have is the message payload for images.

In a response containing many fields and including an image field (say a product 
that has a picture of that product), we have several options:

1.	Return the id of the image, this id can be used to fetch the image in a 
separate api request

2.	Return a url pointing to the image, i.e. http://whatsfresh.org/tuna.jpg

3.	Return an html image tag with the url

4.	Embed the image data itself in the json

For the images/<id> endpoint, we have the same options, plus an additional 
option:

5.	Return the image data in a response of content-type image instead of json

If images have captions that need to be included, then the images/<id> 
endpoint will need to return json. Is that a possibly important/useful 
feature?

My preference:

In image fields within json, return the image id.

In responses to images/<id>, return image data as content-type image.

This requires a separate api call to fetch the image, which may or may not be 
inconvenient/slow for the mobile app, but has these advantages:

it avoids having urls in the repsonse data that could potentially change but 
end up cached (decoupling the endpoint url from the raw data)

it avoids very large responses that will cause the app to wait before 
displaying data

it results in smaller, cleaner, and more easily validated json responses

And it has this disadvantage: requests for the image will have to hit the API 
logic to connect them to the actual image. An image url can bypass the API 
altogether and pull from a fast static file location. 

Returning the image URL is my second choice, but the needs of the mobile app 
should probably dictate the answer here.

Ken