I'm interested in json:api for a RESTful API that I'm starting to work on. I sat down to start digging into the details. I was surprised almost at the outset by this requirement:

A resource object MUST contain at least the following top-level members:

• "id"
• "type"

Later...

A resource object's type and id pair MUST refer to a single, unique resource.

And...

A resource object MAY include a URL in its links object, keyed by "self", that identifies the resource represented by the resource object.

Given that a resource's URL already uniquely identifies that resource, what is the design rationale for requiring a unique (id, type) tuple instead? Why not make the self URL mandatory? Then you would have a unique identifier, and this would allow RESTful APIs for resources that don't necessarily have a distinct ID.

I'll offer an example. I have an authentication API with the URL /api/authentication. A client can POST a username and password to this resource. If the username and password are valid, the API returns a resource representation that includes an API token for the client to use with future requests. I can dream up a "type" for this resource but I really don't have any good ID for it, because it's a singleton resource.

Feedback? Am I doing it wrong?

json:api is the first standard I'm looking at, but at a glance I don't think JSON-LD or HAL require this same (id, type) identifier. The json:api FAQ doesn't explain this design decision and I can't find any other issues related to this design, so apologies if I'm asking an obvious question. Thanks.