API design for server client application

Question

I am currently trying to implement an API that will serve my client with content, and am a bit unsure on how to properly design my API for this. In particular my question is:

Is it better to have specific APIs serving specific scenarios at cost of the client making multiple requests, or is it better to have a do-it-all API that serves every possible value in order to minimize the requests the client has to make.

For example, in an application that lists pictures with descriptions/titles/tags/etc there would be two scenarios:

Page 1:

• Only show the picture in a grid. List all picutres (or a limited amount, say 100)
• Click on a picture to open a view and present additional info: description, title, location, tags, text, comments.

Now I could design this in two ways:

(1)

GET /api/v1/pictures 

returning a JSON containing ALL information, like:

[
{
"pictureUrl": "someUrl",
"text": "someText",
"description": "someDesc",
"tags": "someTags",
"location": "someLocation",
{
]

(2)

GET /api/v1/pictures 

returning an array of pictures with Ids:

[
{
"pictureId" : "someId",
 "pictureUrl": "someUrl"
}
]

(3)

GET /api/v1/picture/{id}

returning the additional picture data:

{
"text": "someText",
"description": "someDesc",
"tags": "someTags",
"location": "someLocation"
}

Obviously in the first variant, the client only needs to do 1 request. With X pictures and Y attributes, this would be a rather big JSON respond, however the client does not need to query any additional info displaying additional information.

Is there a guideline or best practise in these kind of scenarious?

I personally prefer scenario 2, simply because it makes the API more specific and server development easier (imagine multiple tables, multiple joins to get all information). Also, it feels that the API will be less prone to change, since each method is specific and returns the right content. For example:

If I decided to add different kinds of pictures (call it media content), and one could be a video, or gif, ..., changing my existing API would mean changing the return type. The client would have to analyze the returned JSON to figure out what kind of content it is dealing with etc.

I know this is a rather generic question and there is possibly no right answer, I would love to hear some opinions though before I make up my mind.

Answer 1

The answer is: it depends. Basically you should provide separate endpoints, following SRP - it applies to REST design as well.

Also mind the fact that the application will be making multiple calls anyway - every single image will be downloaded separately.

It's also important what kind of clients interact with the application - mobile or web/desktop. In case of mobile interactions it's good to provide all the necessary info in the minimal amount of requests possible - you save the broadband - and it in general works faster.

In this particular case you can also use a kind of resource query language - RQL. It will work as follows:

GET /pictures/

returns the basic info: e.g. ID and pictureURL.

GET /pictures/{ID}

returns the whole available data about picture. This is what you've already defined. The idea is to extend the first endpoint in such a way that it will return all the fields passed via fields query param.

GET /pictures/?fields=pictureURL,ID,tags

This way you've a fast endpoint for returning all the images, a separate endpoint for returning image details and you provide flexible API if the consumer wants to minimize the number of calls.

P.S. Please remove versioning from the URL - headers are much better for versioning.