Accessing a resource by ID.

[cha55son]

At my company we use the siren spec for our API. We've come to an internal disagreement about how resources should be queried by ID. (Maybe this is the improper assumption)

1. Some believe that to access a resource directly it's implied that you tack the id onto the end of the url. Like /resources/id.
2. Some believe there should be an action on the parent of the resource that dictates how to access a resource directly.
3. Some believe that you should pass the href urls around and use those.

Can anyone shed some light on this issue?

[apsoto]

Even though I use Siren, I still maintain a RESTful pattern, so (1) is implied. However, you shouldn't make that part of your documentation as you lose control of the namespace. What if in the future the API has to start using a different hostname, or different path to the resource. By passing the href (3) in API responses, you enable the clients to be able to handle URL changes.

I don't think (2) is correct. I'd use links or sub-entities to navigate around to specific resources.

That's a very general response to a general question. Specific use cases can probably be better answered on the google group

[kevinswiber]

In addition to @apsoto's comments, I'll add how I handle queries.

I put an action on a top level entity that supports queries. The response is often an entity with a "query-results" class or something like that. I use sub-entities to contain each result with the specific information needed in that "list item" representation.

This works fine for queries that might return multiple results. It does get weird when exactly one or zero results are expected, such as when querying by ID. Sometimes, in this case, I return a 302 status code with a Location header pointing to the discovered entity. Some have mentioned adding support for URI Templates[1] to Siren. This would allow you to have URI parameters on actions. That exact syntax has not yet been discussed.

Again, to echo the above statement, this might make for a better topic on the discussion group. :)

[1] https://tools.ietf.org/html/rfc6570

[ericelliott]

1. The behavior of your resource URLs is out of scope for the spec, but I agree that in most resourceful routing, you do it with /collection/id style URLs. However that convention should not be the only way it's communicated to the client, because it depends on information that is out of band.
2. Not an action, a collection of entity hrefs. An action could be used to indicate how the client should add an entity, or query entities, however. See @kevinswiber's reply for more detail on this point.
3. Links can be passed to the client as entity collection hrefs or the links key in the root entity. I typically reserve the latter for the self rel and high-level navigation like first page, previous page, next page, last page, etc.

For a LOT more detail on how to build a good resourceful API, including query handling, etc.., see Chapter 8 from "Programming JavaScript Applications" (scroll down for links to the HTML format chapters).

"Some have mentioned adding support for URI Templates[1] to Siren. This would allow you to have URI parameters on actions."

I'm completely in favor of this, and it deserves an issue here, if it hasn't been created, yet.

[cha55son]

I'll try to reiterate over the opinions so far:

1. This is a nice-to-have but is essentially out-of-band therefore it's not useful to a true siren client.
2. It seems most believe this is a bad idea. (I'll iterate on how I perceived this below)
3. Passing the self link around seems to be the best idea.

To clarify some of my original statements i'll give a really high-level overview of our stack.

SPA (single page app) <=> Rails <=> SirenAPI

Rails is not creating the SapientAPI, Rails is only receiving data from it. Therefore you can imagine how we parse the siren data. Rails makes the request to the SirenAPI, parses the properties of a resource and sends them to the SPA. The SPA then sends the resource ID back to Rails. Rails then queries the SirenAPI for that resource. In this configuration sending the (3) href's around seems funny to me. What is your opinion on this?

(2) Given a resource ID "should" there be a simple way to filter resources? Is it crazy to imagine something like this:

Root of the SirenAPI

{
    ...
    "actions": [
        {
            "name": "get_message",
            "method": "GET",
            "href": "http://example.com/api/messages",
            "title": "Find a specific message",
            "type": "application/x-www-form-urlencoded",
            "fields": [
                {
                    "name": "id",
                    "title": "ID of a message",
                    "type": "NUMBER"
                }
            ]
        }
    ]
}

[apsoto]

IMO, move this to the discussion list.

On Tue, Mar 3, 2015 at 3:35 PM, Chason Choate [email protected]
wrote:

I'll try to reiterate over the opinions so far:

1. This is a nice-to-have but is essentially out-of-band therefore
   it's not useful to a true siren client.
2. It seems most believe this is a bad idea. (I'll iterate on how I
   perceived this below)
3. Passing the self link around seems to be the best idea.

To clarify some of my original statements i'll give a really high-level
overview of our stack.

SPA (single page app) <=> Rails <=> SirenAPI

Rails is not creating the SapientAPI, Rails is only receiving data from
it. Therefore you can imagine how we parse the siren data. Rails makes the
request to the SirenAPI, parses the properties of a resource and sends them
to the SPA. The SPA then sends the resource ID back to Rails. Rails then
queries the SirenAPI for that resource. In this configuration sending the
(3) href's around seems funny to me. What is your opinion on this?

(2) Given a resource ID "should" there be a simple way to filter
resources? Is it crazy to imagine something like this:
Root of the SirenAPI

{
...
"actions": [
{
"name": "get_message",
"method": "GET",
"href": "http://example.com/api/messages",
"title": "Find a specific message",
"type": "application/x-www-form-urlencoded",
"fields": [
{
"name": "id",
"title": "ID of a message",
"type": "NUMBER"
}
]
}
]
}

—
Reply to this email directly or view it on GitHub
#46 (comment).

[cha55son]

Moved: https://groups.google.com/forum/#!topic/siren-hypermedia/doGrFmv41Bk