Questions about JSONAPI's design

1

Hi,

I started using JSONAPI in one of my pet projects, and first of all I like it for providing clear guidance on how one can structure a json-response / request body for resources.
Occasionally I get second thoughts however, as I find certain design decisions unintuitive or maybe not exactly RESTful. So I thought this might be a good place to get some answers about them (points to where I can read about it would be totally fine, too).

  • a resource is defined by its URL, why keep a separate (“id”, “type”) pair for that?
  • id fields kind of assume that for every model type you have multiple instances. I find that a bit overassuming, since I would say that an endpoint like currentUser might make sense that would be a singleton with the current user being a relationship of that resource.
  • why separate attributes and relationships? Relationships could kind of be normal attributes I think that distinguish themselves by the value they have from other attributes.
2

Hey thanks for posting, I’ll try to answer some of your questions simply.

  • A resource can have many types, the URL is just an identifier. In order to support a range of use cases, some level of overlap with some systems ID’s can provide flexibility to support many resource definition strategies (path based, collection + id, API definition, etc…).
  • A current user endpoint would be a stateful endpoint, so in and of itself this would be a non RESTful design.
  • Attributes are simple properties on a resource, relationships are other independent resources which are related to this current resource. In the blog example the author is a relationship to the post because you aren’t going to create a new author record for every post an author creates, and the way to refer to the single resource multiple posts have in common is to link to the resource they share. The relationship is used to help convey the significance or meaning which connects the two resources.

I think some of my hypermedia API design guidelines could help you understand why a lot of this makes sense in {json:api}.

Hope this helps!