[seagrant-dev] Remaining API questions
kennric at osuosl.org
Thu Jul 31 22:10:23 UTC 2014
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
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
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
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.
More information about the seagrant-dev