URL Methods

[smizell]

There is a proposal on the table to add URL methods in some way, either in the RESTful JSON spec, or in the application/url+json media type. The following was put forward by @fosrias.

{
    "url": "http://example.com/article/17",
    "url_methods": {
        "url": ["GET", "PATCH", "DELETE"],
        "author_urls": ["GET", "POST"],
        "categories": {
            "url": ["GET", "POST"]
         }
    }
}

[fosrias]

As a MAY, I think if we do it right, there will be a light bulb go on to client developers who use a bunch of other hacks sending up info in a response to indicate what they are allowed to do. I have seen huge blogs of rpc methods in an array. Basically absent this, your only runtime solution is some blob of metadata regardless. This just tightents it up.

Whether the categories nesting makes sense or it should just be top level on everything and an array of strings is debatable. The issue always is dryness once you repeat in nested lists.

[smizell]

After thinking about this one for quite some time, I'd like to vote a no on this. I know there are only two of us, so one of will have to convince the other :) Allow me to give my reasons. But as a disclaimer, I like this idea overall, but I don't think it needs to be in this specific design pattern.

First, I keep going back to the idea that RESTful JSON is about making it easy to add links/URLs to a JSON response. The person that this will interest is the one who really has no concept of hypermedia. This proposal for url_methods puts us in a place where we are trying to make it easy to get into the hypermedia world and add an additional layer to make runtime affordances easier to convey.

Second, I'm not sure we're making runtime information as expressive as we're hoping here. Take this example:

{
    "url_methods": {
        "books_url": ["GET", "POST"]
    },
    "books_url": "..."
}

This tells you there a resource and the methods you take against that resource. This is not really how I think about hypermedia design and representation. I would probably do something like this:

{
    "books_url": "...",
    "create_book_url": "..."
}

This also maps much easier to ALPS because I can define the expectations around each transition rather than overloading a "book" transition.

Third—and I think this is most important—with this, we've moved past capturing current industry practices and are now creating what we hope becomes an industry practice. I'm leaning toward putting a name to what is already out there and leaving it at that. We can create additional patterns to go along with RESTful JSON, such as a Collection pattern.

Lastly, I think we can capture this here by recommending a single method for each URL. This already happens in HTML. Links <a> are just for GET and <form> include the single method to use. Not saying we have to do that, but it's an option.

---

So to sum up, I think we should leave this out because we want to help people not in this hypermedia world and we want to capture current industry standards as a design pattern. I'm proposing we solve this problems with RESTful JSON and think of other problems/solutions to work on outside of it.

Thoughts?

[smizell]

Per our discussions offline, I think we can close this in favor of describing the nature of links and methods in the document.