Planet PHP
Guest
When looking at REST, the underlying theory, and various interpretations and even HTTP, you’ll find that REST is about singular resources and transfering state of those resources.
There’s very little supporting information about the concept of a collection of resources. Almost every REST API out there will have a need for them, but there doesn’t seem to be a clear definition for them, or an accepted way to technically handle them.
Fielding’s dissertation on REST says:
The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. “today’s weather in Los Angeles”), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author’s hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.
This paragraph is the only place where the word ‘collection’ appears, and it basically says that it’s just another resource. This is good, because it tells us that collections are not a separate concept from other resources and should abide by the same constraints.
However, REST gives us an architecture, we still have to impose our own further contstraints and meaning on top of it. So how do we treat a collection of resources?
Well, when you look at any of the common hypermedia formats, you’ll find that each of them has a slightly different idea about it. However, each of these formats tend to have something in common: they treat items in a collection as a sort of ‘sub-resource’ inside a ‘resource’.
What is a collection, really?
Before we go into some examples, I think it’s worthwhile to discuss this. A collection is a set of resources. Resources may ‘belong’ to a collection in some cases, but resources may also appear in multiple collections.
For example, if my REST api represents blog posts, the same article may appear in a collection that represents all posts from 2017, and all posts written by me.
You might think of a collection as a database table, but I kind of think that that’s not the right analogy. I think a collection is more like a directory on a modern filesystem. The filesystem directory only contains links to files and their position on the filesystem (inode). You could say that a directory has references to files, but you can’t really say that a directory IS a collection of those files.
Files can appear in multiple directories using hardlinks too.
So knowning that, we can translate this to REST terms. A collection is a set of hyperlinks to other resources.
If you’re using HAL, you can express this using:
{
"_links" : {
"self" : { "href" : "/articles/byyear/2017" },
"item" : [
{ "href" : "/articles/1" },
{ "href" : "/articles/2" },
{ "href" : "/articles/3" }
]
}
}
There you have it. In HAL the top-level property names in the
Truncated by Planet PHP, read more at the original (another 28522 bytes)
Читать дальше...
There’s very little supporting information about the concept of a collection of resources. Almost every REST API out there will have a need for them, but there doesn’t seem to be a clear definition for them, or an accepted way to technically handle them.
Fielding’s dissertation on REST says:
The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. “today’s weather in Los Angeles”), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author’s hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.
This paragraph is the only place where the word ‘collection’ appears, and it basically says that it’s just another resource. This is good, because it tells us that collections are not a separate concept from other resources and should abide by the same constraints.
However, REST gives us an architecture, we still have to impose our own further contstraints and meaning on top of it. So how do we treat a collection of resources?
Well, when you look at any of the common hypermedia formats, you’ll find that each of them has a slightly different idea about it. However, each of these formats tend to have something in common: they treat items in a collection as a sort of ‘sub-resource’ inside a ‘resource’.
What is a collection, really?
Before we go into some examples, I think it’s worthwhile to discuss this. A collection is a set of resources. Resources may ‘belong’ to a collection in some cases, but resources may also appear in multiple collections.
For example, if my REST api represents blog posts, the same article may appear in a collection that represents all posts from 2017, and all posts written by me.
You might think of a collection as a database table, but I kind of think that that’s not the right analogy. I think a collection is more like a directory on a modern filesystem. The filesystem directory only contains links to files and their position on the filesystem (inode). You could say that a directory has references to files, but you can’t really say that a directory IS a collection of those files.
Files can appear in multiple directories using hardlinks too.
So knowning that, we can translate this to REST terms. A collection is a set of hyperlinks to other resources.
If you’re using HAL, you can express this using:
{
"_links" : {
"self" : { "href" : "/articles/byyear/2017" },
"item" : [
{ "href" : "/articles/1" },
{ "href" : "/articles/2" },
{ "href" : "/articles/3" }
]
}
}
There you have it. In HAL the top-level property names in the
Truncated by Planet PHP, read more at the original (another 28522 bytes)
Читать дальше...