I am developing a RESTful API designed primarily (but not exclusively) for consumption by a web application. For the purposes of this question, the API is a set of GET endpoints. The main endpoint is /people/ and understands a large amount of query parameters to refine the result set.

The web application's splash page initiates this request:

GET http://my.api/people/
Accept: application/json

And this responds with a body of:

  "results": [
      "name": "john",
      "age": "21",
      "_links": {
        "self": "/people/john/"
    ... more people ...
  "_links": {
    "self": "/people/"

The results array is used by the web application to populate a list view of the people, with their name and age, and also an image of the person.

The image can be retrieved with such a request:

GET http://my.api/people/john
Accept: image/png

From the perspective of the web application, this presents a number of difficulties.

  • The _links.self of an individual person can be used in a HTML <img> element as the src, however the request generated by this has a header of Accept: */*, which does not sit well with the API as the global conventional default type is application/json.

  • The image/png request could be manually sent via Javascript but this can result in a large number of concurrent XHR requests, possibly beyond the concurrency limit of some browsers

As I also have final say in the design of the API other possibilities are on the table:

  • The /people/ endpoint could be modified to return the image representation as Base64 (or some other text format) as part of the application/json response. This could also be excluded by default (and included manually with a include=images query parameter), so that requests are not forced to download image data for each response. This increases the response size massively, leading to slower response times for clients (especially mobile users) and potentially a cost increase due to increased outbound data from the hosting platform of the API.

  • The /people/john endpoint could be updated to default to an image/png response, however this goes against the grain of the rest of the API and is a change aimed exclusively at one client of the API.

  • The /people/ endpoint could return, in each result's _links dictionary, a direct link to the image e.g. my.api/images/people/john.png. This is looking like the best option with few drawbacks, however I do not know how well this incorporates into REST / HATEOAS.

What is the most appropriate solution, from a REST / HATEOAS architectural point of view, for retrieving the image representation of a resource as well as the JSON representation

Related posts

Recent Viewed