-
Notifications
You must be signed in to change notification settings - Fork 878
"resource" vs. "entity" #966
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
Comments
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. |
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. |
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. |
That was brought up the last go around as well! |
How about "resource class" and "resource objects"? Combines REST and OO naming. |
💯 from me. One thing to mention - it will mess up naming in most of implementations, and that is HEAVY 😞 |
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 😉 ) |
😲 You are genius @meshuga! 👍 |
...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. |
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? |
Compare https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm section 5.2 and http://jsonapi.org/format/#document-resource-objects |
If the terminology is not going to change, I'll update that old PR. |
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. 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" |
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". |
@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. |
@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. |
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: 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. |
No. This has nothing to do with types. In REST terms, |
That is exactly what I meant
Which means that although the backend knows this is the same data, it should stay privy to the backend. It got a bit convoluted in my poor example. |
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? |
|
Oh, yeah that's a good one. Thanks Steve. |
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 For other APIs that are more "RESTful", there is a direct mapping of URLs and |
In my opinion the JSON API and implementations like karthasis and crnk focuses to much on the entity-meaning of resource. |
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.
The text was updated successfully, but these errors were encountered: