json - API design for server client application -

i trying implement api serve client content, , bit unsure on how design api this. in particular question is:

is better have specific apis serving specific scenarios @ cost of client making multiple requests, or better have do-it-all api serves every possible value in order minimize requests client has make.

for example, in application lists pictures descriptions/titles/tags/etc there 2 scenarios:

page 1:

• only show picture in grid. list picutres (or limited amount, 100)
• click on picture open view , present additional info: description, title, location, tags, text, comments.

now design in 2 ways:

(1)

get /api/v1/pictures  

returning json containing information, like:

[ { "pictureurl": "someurl", "text": "sometext", "description": "somedesc", "tags": "sometags", "location": "somelocation", { ] 

(2)

get /api/v1/pictures  

returning array of pictures ids:

[ { "pictureid" : "someid",  "pictureurl": "someurl" } ] 

(3)

get /api/v1/picture/{id} 

returning additional picture data:

{ "text": "sometext", "description": "somedesc", "tags": "sometags", "location": "somelocation" } 

obviously in first variant, client needs 1 request. x pictures , y attributes, rather big json respond, client not need query additional info displaying additional information.

is there guideline or best practise in these kind of scenarious?

i prefer scenario 2, because makes api more specific , server development easier (imagine multiple tables, multiple joins information). also, feels api less prone change, since each method specific , returns right content. example:

if decided add different kinds of pictures (call media content), , 1 video, or gif, ..., changing existing api mean changing return type. client have analyze returned json figure out kind of content dealing etc.

i know rather generic question , there possibly no right answer, love hear opinions though before make mind.

the answer is: depends. should provide separate endpoints, following srp - applies rest design well.

also mind fact application making multiple calls anyway - every single image downloaded separately.

it's important kind of clients interact application - mobile or web/desktop. in case of mobile interactions it's provide necessary info in minimal amount of requests possible - save broadband - , in general works faster.

in particular case can use kind of resource query language - rql. work follows:

get /pictures/ 

returns basic info: e.g. id , pictureurl.

get /pictures/{id} 

returns whole available data picture. you've defined. idea extend first endpoint in such way return fields passed via fields query param.

get /pictures/?fields=pictureurl,id,tags 

this way you've fast endpoint returning images, separate endpoint returning image details , provide flexible api if consumer wants minimize number of calls.

p.s. please remove versioning url - headers better versioning.