# API endpoints and unique resource ids

**URL:** <https://discuss.jsonapi.org/t/api-endpoints-and-unique-resource-ids/1211>\
**Category:** Uncategorized\
**Created:** [February 20, 2018, 4:08pm UTC](https://discuss.jsonapi.org/t/api-endpoints-and-unique-resource-ids/1211 "2018-02-20T16:08:22Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![marceloverdijk](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/marceloverdijk/32/521_2.png) [@marceloverdijk](https://discuss.jsonapi.org/u/marceloverdijk)\
**Post date:** [February 20, 2018, 4:08pm UTC](https://discuss.jsonapi.org/t/api-endpoints-and-unique-resource-ids/1211/1 "2018-02-20T16:08:22Z")

</div>

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?

---

<div class="post-metadata">

**Author:** ![michaelhibay](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/michaelhibay/32/405_2.png) [@michaelhibay](https://discuss.jsonapi.org/u/michaelhibay)\
**Post date:** [February 21, 2018, 5:32pm UTC](https://discuss.jsonapi.org/t/api-endpoints-and-unique-resource-ids/1211/2 "2018-02-21T17:32:07Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![marceloverdijk](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/marceloverdijk/32/521_2.png) [@marceloverdijk](https://discuss.jsonapi.org/u/marceloverdijk)\
**Post date:** [February 21, 2018, 9:40pm UTC](https://discuss.jsonapi.org/t/api-endpoints-and-unique-resource-ids/1211/3 "2018-02-21T21:40:16Z")

</div>

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`”?

---

<div class="post-metadata">

**Author:** ![michaelhibay](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/michaelhibay/32/405_2.png) [@michaelhibay](https://discuss.jsonapi.org/u/michaelhibay)\
**Post date:** [February 22, 2018, 10:45am UTC](https://discuss.jsonapi.org/t/api-endpoints-and-unique-resource-ids/1211/4 "2018-02-22T10:45:43Z")

</div>

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!