API endpoints and unique resource ids


#1

I’m looking for some advice regarding JSON:API endpoints.

In a non JSON:API I currently have something like:

/seasons/2018/matches/1

This retrieves the the 1st match in 2018.
Just like there is a first match in 2017.

This Match resource should have a unique id, something like 2018-01 probably.

But this doesn’t match anymore with the endpoint scheme.

Off course I could change that to /matches/2018-01 but the former looks better imo.

How are others using such a schemes with JSON:API?


#2

I think the best format would be something like: /matches?filter[season]=2018&filter[week]=1. The match resource does indeed need a unique ID, but in no way does it need to be human readable.

This is a much flatter resource design, with the relationships and filtering more clearly defined in query parameters, without having the URL hierarchy hold any special semantic meaning.


#3

Thanks Michael!

The flattened design is not bad indeed, and I agree this way the URL hierarchy does not hold any semantic meaning anymore.

Is my assumption correct that a match’s self link should look like “/matches/2018-01” then? (or perhaps an id that is not human readable).
And to find a match by a logical year / round use “/matches?filter[season]=2018&filter[week]=1”.

Btw does JSON:API recommend to use “filter[season]=2018” instead of e.g. “filter.season=2018”?


#4

The self link would be the canonical URL for the resource. If you choose to make the ID format 2018-01, then yes it would be. However, I’m unsure if you expect to have matches for each team of your API, which would indicate a collision. I prefer and advise the use of some non-sequential identifier (UUID) over the use of something human readable, but this isn’t always possible or ideal.

This feels like a football API, and if true you would probably need more filter parameters to narrow the query to a single teams first week, or you could optimize the design to you implementation to suit. I’m sure you’re aware of this, but I add for completeness of the answer.

As for the filter style, there are a few posts here which aggregate some common formats, but the specification does not have any recommendations or suggestions.

Good luck, and I hope this helps!