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?
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.
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”?
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!