"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.

[bintoro]

@masterspambot Thank you, I'm familiar with that work. The point of this discussion is that REST and JSON API talk about different things when they talk about resources.

[NinoFloris]

Forgive me for not grasping what the exact problem was earlier on.

@bintoro Ok so you would like (for instance) to see type and id folded into an HTTP resource identifier as to solidify the connection between these concepts and remove the wiggle room the current specification gives in terms of naming things?

Following this thought:
The underlying type (which we call JSON API resources) for the representation of one or multiple REST resources should not matter. And should stay implementation detail, not interface information.

E.g. "/articles/1/author" has the same underlying OO class or JSON API type "people" its data is represented at both REST resource "/articles/1/author" and "/people/34". Why express that both these resources have a common underlying instance or JSON API resource, this should be inferred from for instance links or relationships to REST resources. Is this the mismatch you talk about?

As for your previous post where did you mention this yesterday, IRC? I'm looking to contribute and to get up to speed.

[bintoro]

[...] REST resource "articles/1/author" and "people/34". Why express that both these resources have a common underlying type, this should be inferred from relationships to resources. Is this the mismatch you talk about?

No. This has nothing to do with types. In REST terms, articles/1/author and people/34 are two distinct resources. It doesn't matter if the data behind them is the same. By contrast, JSON API describes an object model where object identity is independent of the URI and the two paths may in fact refer to the same resource.

[NinoFloris]

That is exactly what I meant

The underlying type (which we call JSON API resources) for the representation of one or multiple REST resources should not matter. And should stay implementation detail, not interface information.

Which means that although the backend knows this is the same data, it should stay privy to the backend.
And JSON API exposes this for no good reason.

It got a bit convoluted in my poor example.

[yankeeinlondon]

How valuable is having this distinction separated? I'm not meaning to question it but it certainly felt redundant when I ran into this the first time (which was yesterday) and I suspect it will remain a source of at least initial confusions when people ponder adoption. Can someone illustrate a case where this separation is used?

[steveklabnik]

Can someone illustrate a case where this separation is used?

GET /articles/latest is a completely different resource, yet may return exactly that same entity.

[yankeeinlondon]

Oh, yeah that's a good one. Thanks Steve.

[nsforge]

We're currently in the process of adopting JSON API in a number of systems, and these systems have a number of endpoints that provide a "data dump" to clients (usually mobile apps) that contains large numbers of objects, so there may be only a tenuous relationship between the type/id tuples contained in a response body and the URL (similar to the GET /articles/latest example above, but more extreme).

For other APIs that are more "RESTful", there is a direct mapping of URLs and type/id tuples, but the flexibility of being able to decouple the two concepts is actually a requirement of our architecture.

[bmaehr]

In my opinion the JSON API and implementations like karthasis and crnk focuses to much on the entity-meaning of resource.
JSON can describe structured documents and you stick at flat entities and their relationsships.
As long as the API not allow to embed hierarchies of entities (without ids) there will always the need of workaround the spec.
Even your simple article example could be seen as a structure with a embedded sub-entity for the header and many sub entities the paragraphs. And then you are leaking the storage-architekture over JSON API to the frontend.