Multiple calls or combine data into a "collection"?

I’m looking to consolidate some of our old API endpoints and I’m curious as to the best approach in terms of the new APIs using the JSON API Schema.

Currently, we have 2 endpoints, one provides a list of data objects, that have to then be filtered by our frontend, as it includes events, past and future. The second endpoint is returning some data that is relevant to the first endpoint.

Regarding the first endpoint, I could split that into 2 new endpoints, one for past events, one for future events.

Or, I was wondering if a single endpoint to show past events, future events, and the data from the 2nd endpoint, as an overall “collection”?

So, do I take 2 endpoints and split the 1st into 2, meaning 3 calls in total? Or, can I create a “collection” endpoint that combines and splits the 2 current endpoints to give me the past events, future events and the “other” data in 1 call?

Below is the kind of data structure I was tihnking of:

{
    data: {
        type: "a-collection-of-things",
        attributes: {
            past-events: [...],
            future-events: [...],
            event-listing-data: [...]
        }
   }
}

Without knowing more about your application, it’s hard to know what’s really best.

Just from this, I’d suggest your “data that is relevant to the first endpoint” might be presented as a resource, and the sequence of events be presented as a to-many relationship. The client could then use filtering to look only at past events or future events, and then can be sorted in chronological or reverse-chronological order. Pagination might be important there, depending on the volume of event data.

-Fred

1 Like

Hey fdrake,

Sorry for the vagueness, I have to be careful what information I share.

I wasn’t too clear about the current 2nd endpoint, where I initially said “The second endpoint is returning some data that is relevant to the first endpoint.” The data is relevant, without any actual explicit relationship mapping.

An example would be where the (currnet) 1st endpoint is returning past and future events, the 2nd would be a list of attendee numbers for all past events.

Basically, am I OK to split ‘attributes’ into 3 sections, one for each block of data, or split it into separate endpoints?

Ultimately, you can arrange the data however it makes sense for your application; the most important API contract is between the service and the UI layer.

If you’re not applying JSON:API concepts, though, there’s no reason to use JSON:API.

-Fred

But I would like to apply JSON API concepts, however it is tricky to do some times are the documentation does not provide many examples.

Then my inclination would be to expose the sequence of events as a single collection, /events, with filtering so the client can select the range of events they want from the timeline, using query parameters such as filter[before], filter[since], or similar. Then, each event would be a resource from the collection. For past events, attendee counts and similar information could be included directly. For future events, such values could be omitted or null. Individual events could then be exposed at /events/{id}.

-Fred