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

Comments

Projects
None yet
@bintoro
Contributor

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

This comment has been minimized.

Show comment
Hide comment
@dgeb

dgeb Jan 13, 2016

Member

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.

Member

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

This comment has been minimized.

Show comment
Hide comment
@tkellen

tkellen Jan 13, 2016

Member

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.

Member

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

This comment has been minimized.

Show comment
Hide comment
@bintoro

bintoro Jan 13, 2016

Contributor

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.

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@tkellen

tkellen Jan 13, 2016

Member

That was brought up the last go around as well!

Member

tkellen commented Jan 13, 2016

That was brought up the last go around as well!

@oliver-xapix-io

This comment has been minimized.

Show comment
Hide comment
@oliver-xapix-io

oliver-xapix-io Jan 13, 2016

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

oliver-xapix-io commented Jan 13, 2016

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

@masterspambot

This comment has been minimized.

Show comment
Hide comment
@masterspambot

masterspambot Feb 13, 2016

Contributor

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

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@meshuga

meshuga 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 😉 )

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

This comment has been minimized.

Show comment
Hide comment
@masterspambot

masterspambot Feb 13, 2016

Contributor

😲 You are genius @meshuga! 👍

Contributor

masterspambot commented Feb 13, 2016

😲 You are genius @meshuga! 👍

@bintoro

This comment has been minimized.

Show comment
Hide comment
@bintoro

bintoro Feb 13, 2016

Contributor

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

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@NinoFloris

NinoFloris 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?

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

This comment has been minimized.

Show comment
Hide comment
@meshuga

meshuga 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

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

This comment has been minimized.

Show comment
Hide comment
@bintoro

bintoro Feb 14, 2016

Contributor

@NinoFloris 243a804

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

Contributor

bintoro commented Feb 14, 2016

@NinoFloris 243a804

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

@NinoFloris

This comment has been minimized.

Show comment
Hide comment
@NinoFloris

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

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

This comment has been minimized.

Show comment
Hide comment
@bintoro

bintoro Feb 14, 2016

Contributor

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

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@masterspambot

masterspambot Feb 14, 2016

Contributor

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

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@bintoro

bintoro Feb 14, 2016

Contributor

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

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@NinoFloris

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

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

This comment has been minimized.

Show comment
Hide comment
@bintoro

bintoro Feb 14, 2016

Contributor

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

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@NinoFloris

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

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

This comment has been minimized.

Show comment
Hide comment
@ksnyde

ksnyde 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?

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

This comment has been minimized.

Show comment
Hide comment
@steveklabnik

steveklabnik Feb 24, 2016

Contributor

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.

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@ksnyde

ksnyde Feb 24, 2016

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

ksnyde commented Feb 24, 2016

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

@nsforge

This comment has been minimized.

Show comment
Hide comment
@nsforge

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

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

This comment has been minimized.

Show comment
Hide comment
@bmaehr

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

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