Get multiple sub-resources with one single endpoint

Question

I'm currently trying to build an API to be used for reporting-purposes. Therefore I do only need to implement some GET endpoints.

In my simple scenario there are two resources. An event and the creator of the event. Each event has one creator.

For one report I do need all events created between a given time-frame.

• GET /api/Events/?start=someStartDate&end=someEndDate

which will get me those events. Now I do need the creators as well.

How can this be done without calling GET /api/Creators/{creatorId} for each event returned by the first call (which can be quite a lot)?

It's no option to pass event-ids as they are Guids which would exceed the maximum url-length for GET. Are there any best practices like a new endpoint? But how would this endpoint look like?

I also thought about including the creator directly into the EventResource. Unfortunately, this got me also headaches as of a creator can have a list of events (which have a creator, which has events, ... and so on).

Would it make sense to have two kinds of resources like some sort of base-eventresource which has only simple properties and an extenden event-resource which has other resources encapsulated? But where should I draw the line? Also I then would need two endpoints for each resource (base and extended) which may confuse the client.

Hope here is the right place for such kind of questions. Maybe the solution is obvious but I'm already in too deep to see it.

Answer 1

You may follow approach similar to the one of JIRA API, by using the "expand" parameter. The client itself will decide, how detailed must be the information and pass some "expand" value to server, requesting additional details, as shown in following examples:

Without additional details

Server responds with only id and link to self for event creators.

GET /events/?filter1=value1&filter2=value2
[{
    "id" : "124"
    "date" : "12-10-2016",
    "creator" : { 
        "id" : "1" 
        "_links" : [{ "self" : ".../creators/1" }]
    }, 
    "_links" : [{ "self" : ".../events/124" }]
}]

With information about creators

Client appends "expand" parameter:

GET /events/?filter1=value1&filter2=value2&expand=creators
[{
    "id" : "124"
    "date" : "12-10-2016",
    "creator" : { 
        "id" : "1",
        "name" : "John Doe",
        "events" : { 
             "_links" : [{ "self" : ".../creators/1/events" }]
        } 
        "_links" : [{ "self" : ".../creators/1" }]
    }, 
    "_links" : [{ "self" : ".../events/124" }]
}]