"resource" vs. "entity"

[bintoro]

I've come to believe that not resolving the JSON API resource vs. HTTP resource terminology conflict prior to v1.0 was a mistake, so I'm opening this issue to elicit a decision on whether it's going to be this way forever.

When writing code that utilizes JSON API but is not totally JSON API -centric, I now find myself avoiding the term "resource" altogether. Using it to refer to the individual entities, or records, just feels wrong and would be confusing to anyone not familiar with the JSON API nomenclature.

FWIW, OData uses "entity" in accordance with the REST vocabulary.

[dgeb]

I hear you. This is undoubtedly a common source of confusion. And the confusion spreads to implementations, which naturally model their terminology upon the spec.

We could certainly change the terminology without breaking the spec. I am not opposed if we can agree on a replacement.

[tkellen]

I'm 👍 to this as well. I attempted it with the term "record" at some point last year and while it read pretty well we were close to 1.0 and felt it wasn't worth the effort to vet.

[bintoro]

I quite like "record" too. The only concern I have is if it has too much of an "entry in a datastore" vibe to it.

[tkellen]

That was brought up the last go around as well!

[oliver-xapix-io]

How about "resource class" and "resource objects"? Combines REST and OO naming.

[masterspambot]

💯 from me. One thing to mention - it will mess up naming in most of implementations, and that is HEAVY 😞

[patrykorwat]

In Katharsis we stayed with term resource which is now used widely within the library (http://katharsis.io/docs, https://github.com/katharsis-project/katharsis-core/search?utf8=%E2%9C%93&q=resource), so it might be better to emphasize the distinction between JSON resource and HTTP resource in the documentation.

PS. also other projects use term resource + it's not that hard to make a distinction - https://youtu.be/U7LTdj5cvTM?t=23m44s (sorry, it's in Polish 😉 )

[masterspambot]

😲 You are genius @meshuga! 👍

[bintoro]

[...] so it might be better to emphasize the distinction between JSON resource and HTTP resource

...or we could do away with the concept altogether.

The meaningful unit is the resource object. That the objects are intended as representations of something called a "resource" is just a narrative that has no functional significance.

[NinoFloris]

So uhm... What exactly is the difference?

I can speculate but nowhere it states a full definition, is there a previous issue you can refer me to?

[patrykorwat]

Compare https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm section 5.2 and http://jsonapi.org/format/#document-resource-objects
In big summary, Fielding's resources are JSON API's top level objects

[bintoro]

@NinoFloris 243a804

If the terminology is not going to change, I'll update that old PR.

[NinoFloris]

Ok great, thanks.

So the only difference really is resource (not resource object) is a set of entities and not an actual entity itself, which is the case in HTTP.
Quite like OO then.
@meshuga And Fielding's resource identifiers are JSON API's "self" links? Excluding relationships "self" as their "self" is not a resource but a field (which could have different naming e.g. people/author) right?

Type and Id form the identifying tuple that is an HTTP resource and you should (or must?) map these cleanly to their URL (resource identifier) "/people/1"

[bintoro]

The problem with "resource" is not that it has a different meaning than in some guy's dissertation. It's that the word appears 211 times in the HTTP RFC 7231. Applying the RFC's language to JSON API resources will give the reader lots of wrong ideas.

HTTP itself does not have any element resembling the JSON API resource because HTTP goes directly from endpoints to representations. As I mentioned yesterday, JSON API could also just stick to representations and avoid the whole mess. The concept of a resource in JSON API is fundamentally unnecessary.

HTTP suggests "content" as a synonym for representational data, so perhaps "content object" might be a suitable replacement for "resource object" in a representation-centric revision.

Not replacing "resource" with anything would allow implementors to continue using whatever name they like for the entities backing the content objects.

As a possible drop-in replacement for "resource" I'd still favor "entity", maybe "instance".

[masterspambot]

@bintoro please look at what @meshuga mentioned prevoiusly. Resource is the very core paradigm of REST and JSON API is simply implementation of REST level 3 called HATEOAS. This is the reasoning behind using and not changing resource nomenclature.