Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

"resource" vs. "entity" #966

Open
bintoro opened this issue Jan 13, 2016 · 24 comments
Open

"resource" vs. "entity" #966

bintoro opened this issue Jan 13, 2016 · 24 comments

Comments

@bintoro
Copy link
Contributor

@bintoro bintoro commented Jan 13, 2016

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
Copy link
Member

@dgeb dgeb commented Jan 13, 2016

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
Copy link
Member

@tkellen tkellen commented Jan 13, 2016

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
Copy link
Contributor Author

@bintoro bintoro commented Jan 13, 2016

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
Copy link
Member

@tkellen tkellen commented Jan 13, 2016

That was brought up the last go around as well!

@oliver-xapix-io
Copy link

@oliver-xapix-io oliver-xapix-io commented Jan 13, 2016

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

@masterspambot
Copy link
Contributor

@masterspambot masterspambot commented Feb 13, 2016

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

@meshuga
Copy link

@meshuga meshuga commented Feb 13, 2016

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
Copy link
Contributor

@masterspambot masterspambot commented Feb 13, 2016

😲 You are genius @meshuga! 👍

@bintoro
Copy link
Contributor Author

@bintoro bintoro commented Feb 13, 2016

[...] 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
Copy link

@NinoFloris NinoFloris commented Feb 14, 2016

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?

@meshuga
Copy link

@meshuga meshuga commented Feb 14, 2016

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
Copy link
Contributor Author

@bintoro bintoro commented Feb 14, 2016

@NinoFloris 243a804

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

@NinoFloris
Copy link

@NinoFloris NinoFloris commented Feb 14, 2016

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
Copy link
Contributor Author

@bintoro bintoro commented Feb 14, 2016

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
Copy link
Contributor

@masterspambot masterspambot commented Feb 14, 2016

@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
Copy link
Contributor Author

@bintoro bintoro commented Feb 14, 2016

@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
Copy link

@NinoFloris NinoFloris commented Feb 14, 2016

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
Copy link
Contributor Author

@bintoro bintoro commented Feb 14, 2016

[...] 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
Copy link

@NinoFloris NinoFloris commented Feb 14, 2016

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.

@ksnyde
Copy link

@ksnyde ksnyde commented Feb 24, 2016

2016-02-24_15-27-05

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
Copy link
Contributor

@steveklabnik steveklabnik commented Feb 24, 2016

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.

@ksnyde
Copy link

@ksnyde ksnyde commented Feb 24, 2016

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

@nsforge
Copy link

@nsforge nsforge commented Apr 8, 2016

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
Copy link

@bmaehr bmaehr commented Mar 21, 2018

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
You can’t perform that action at this time.