Does JSONAPI love singular resources?


#1

What is jsonapi’s stance on singular resources? e.g. /profile which implies the profile for the authenticated user. I’m specifically interested in the payload for non-GET requests requiring an id attribute even though it may not be used for lookup.


#2

JSON API talks in terms of collections (which are the general case) but, at the end of the day, singular resources are totally allowed and are often necessary.

For consistency, JSON API still requires that they have an id (we don’t want clients to need custom parsing logic for these cases), but you can put any sensible value you want there. In your case, the id of the corresponding user might make sense (whether that be an email, username, or db index).

So for a hypothetical user with unique id "bob", you’d have:

GET /profile

{
  "data": {
    "type": "profiles",
    "id": "bob",
    "attributes": { /* profile data here */ }
  }
}

and then

PATCH /profile

{
  "data": {
    "type": "profiles",
    "id": "bob",
    "attributes": { /* profile data here */ }
  }
}

Basically, /profile just functions like an alias (on both GET and PATCH) for /profiles/bob, and that’s fine. If you wanted to make this connection clearer, you could use /profiles/active-user as the URI, instead of /profile, but JSON API doesn’t require that you do so.

Finally, if you want to make bob’s profile available at both /profile (or /profiles/active-user) when bob is signed in, and at /profiles/bob (e.g. for administrators), you could put a different "self" link at the top level and at the resource object level, like so:

GET /profile

{
  "links": {
    "self": "http://example.com/profile" // must be uri used to make the request.
  }
  "data": {
    "type": "profiles",
    "id": "bob",
    "attributes": { /* profile data here */ },
    "links": {
      "self": "http://example.com/profiles/bob" // canonical URI for this particular profile
    }
  }
}

#3

Thanks for the reply! Makes sense :smile:


#4

What’s the thought process behind your active-user comments?
Is there a reference that it’s from, or was it just a made up example?


#5

There’s no specific recommendation in the spec for handling the page that shows the active user’s profile, if that’s what your asking. And the spec doesn’t constrain your URIs at all (except for some query parameter meanings).

My suggestion of /profiles/active-user for the URI instead of /profile was just to more clearly suggest to humans that the URI is picking out one resource from a typed collection (i.e. the active user from the set of profiles) in the same way /people/1 is the spec’s suggested/conventional URI for requesting the resource {type: people, id: 1}.


#6

Yup, just asking for clarification on your thought process to that. I wasn’t quite able to understand with the original post that active-user was just the string form of an ID in your example. I understand it now, thanks!


#7

Sure. And, just to clarify, "active-user" probably wouldn’t be the "id" of the JSON:API resource object returned at that URI; that "id" might be “bob” or similar, as in the example response.

My point was just meant to be that /profiles/active-user is a nice form because of its parallelism with /profiles/1. Again, not a perfect analogy, since "1" there is probably the literal value of an "id" key, whereas "active-user" isn’t, but it’s clearer imo than /profile.


#8

Related question…
Should the type still be plural? or does singular make sense, too?
Thanks!


#9

The plurality of the type does not reflect the plurality oft he resource. According to the spec, it doesn’t matter if the type is plural or singular so long as it’s consistent. http://jsonapi.org/format/#document-resource-object-identification


#10

Thanks for the clarification.