Add definition of resource & FAQ entry

[bintoro]

Currently no definition of resource exists in the spec, yet the very first sentence establishes that it is a key concept.

This PR adds a definition for resource in the intro section along with a FAQ entry detailing the difference from an HTTP resource and explaining why this leads to the ID+type requirement. It also felt appropriate to bring some mention of HTTP into the very beginning.

Addresses: #354, #373

[dgeb]

Thanks for this @bintoro. I think this will clear up many misunderstandings.

👍

[kjwierenga]

I'm a bit confused by the overloading of the word 'resource'.

So we have the HTTP definition of what a 'resource' is. We have the Fielding definition of what a 'resource' is. Are the HTTP definition and the Fielding definitions the same? I assume they are.

Then we have the JSON API definition of what a resource is and somewhere I read:

In terms of JSON API, resources are just objects.

As far as I can see the JSON response documents are representations of resources (both terms in Fielding definition). In my opinion we should not use the word 'resource' in the JSON API spec to mean a different thing.

For example:

Primary data MUST appear under a top-level key named "data". Primary data MUST be either a single resource object, an array of resource objects, or a value representing a resource relationship.

Could be changed to (remove 'resource' before 'object').

Primary data MUST appear under a top-level key named "data". Primary data MUST be either a single object, an array of objects, or a value representing a resource relationship.

In fact everywhere 'Resource object' could be replaced by just 'object'.

Come to think of it 'object' isn't really a good name, because it's just 'data'; there is no behavior... (The objects in JavaScript Object Notation are not really objects actually).

In this Pull Request I read:

A [JSON API] resource is an entity that has attributes and may be associated with other resources via relationships. JSON API does not impose constraints on what a resource may represent. For example, a resource could describe an object in a database, an event that has occurred, or the state of a service.

Why overload the word 'resource'

One way to make the difference would be to use the word 'entity'. The second sentence to mention 'resource' in the spec would then read like this

The document's "primary data" is a representation of the entity, collection of entities, or entity relationship primarily targeted by a request.

Sections would be renamed like this:

• 'Resource Objects' becomes 'Entities'
• 'Resource Attributes' becomes 'Entity Attributes'
• 'Resource Identification' becomes 'Entity Identification'
• 'Resource Types' becomes 'Entity Types'
• 'Resource Relationships' becomes 'Entity Relationships'
  etc.

When you use a different word, then every occurence of the word 'resource' in the current spec raises an important question: 'Is this an entity or is this a [HTTP/Fielding] resource'.

Am I completely off track here? Or would using a different word clarify the spec?

[gr0uch]

I'm curious what the initial motivation for using the word "resource" instead of "entity" was.

[kjwierenga]

The definition of resource within the JSON API spec is different from the definition in HTTP. This leads to confusion/ambiguity in the spec. By using a different word, be it 'object' or 'entity' we can remove this ambiguity. I chose 'entity' because I think it fits the purpose. A JSON fragment like the following isn't an object (it has no behavior. In fact it's just data.

{
    "id":"1",
    "type":"people",
    "name":"Steve"
}

Maybe there is a better word?

[bintoro]

@kjwierenga, your interpretation is correct. The word "object" is currently used to refer to JSON objects, but "entity" would be workable.

I don't want to get too deep into the debate whether the terminology should be changed, as it doesn't bother me that much, but I would certainly support such a change.

I don't find the word "resource" particularly important. It could be "entity" or whatever. The success of a standard hinges mostly on its concepts, not the choice of an individual word, and nobody's proposing to change the concept of what is today called "resource".

[kjwierenga]

Upon scanning the spec for the word 'resource' it actually isn't a big problem because most if not all uses are in fact the JSON API definition of 'resource'. The HTTP definition of 'resource' is avoided by using 'endpoint' instead or by the phrase 'the URL that represents the resource'.

Sometimes [JSON API] 'resource' and 'resource object' are used in the same sentence. What is the difference between [JSON API] 'resource' and 'resource object' if any?

I guess some problems of definition come up in the 'Responses' section. I think it uses 'resource' in the HTTP definition.

I don't think it's a big deal although using a different name would remove all ambiguity.

[dgeb]

What is the difference between [JSON API] 'resource' and 'resource object' if any?

A resource object is the JSON representation of a resource (which is a more abstract term).

---

I'm not crazy about the alternative "entity". It doesn't seem to me that an entity member in a link object would be as clear as resource. But then again, it's hard for me to look at this with fresh eyes.

We should at least clarify terminology as @bintoro is attempting with this PR.

/cc @steveklabnik @wycats

[bintoro]

@kjwierenga The spec never uses "resource" in the HTTP meaning, or if it does, it's a bug. A resource object is the JSON representation of a resource.

[tkellen]

@bintoro would you be willing to rebase and ping when ready?

[bf4]

@bintoro @tkellen This seems to have become forgotten :( also ref #966

[kjwierenga]

This can be closed?

[jelhan]

@dgeb I think we want to revisit this one. I think this clarification if the term resource used in the spec would help a lot to prevent confusion.