Question

I’ve been reading articles about RESTful services for a while, and I understand the importance of using VERBS against RESOURCES.

But there’s one thing I fail to understand. What happens if we need to invoke a certain action that is not part of CRUD?

For example, consider I want to make a cat jump. Which format should we use?

Is the following RESTful?

http://host/cats/123/jump

Answer 1

If cats/123 represents a resource then think about it this way: that resource can have many states (eating, walking, sleeping, jumping, pissing, …). When you are designing an API using the REST architectural style, you want to permit a client application to make allowable requests to the resource that will change its state.

In the context of cats/123, you could do this through a series of POST requests that will cause the state of the resource to change. Taking advantage of the hypermedia capability in REST you could create a process like the requests and responses shown below. Notice that the allowable links change as a response to the POST. Also, the client application would be coding to the properties contained in the Links array and not the actual URI’s contained in the Href properties.

Request:

GET cats/123

Response:

{
    "Color" : "black",
    "Age"   : "2",
    "Links":[
    {
        "Food":"kibbles",
        "Method":"POST",
        "Href":"http://cats/123",
        "Title":"Feed the cat"
    },
    {
        "Scare":"yell real loud",
        "Method":"POST",
        "Href":"http://cats/123",
        "Title":"Scare the cat"
    }]
}

Request:

POST cats/123

{
    "Food":"kibbles"
}

Response:

{
    "Color" : "black",
    "Age"   : "2",
    "Tummy" : "full"
    "Links":[
    {
        "Sleep":"lap",
        "Method":"POST",
        "Href":"http://cats/123",
        "Title":"Pet the cat"
    },
    {
        "Scare":"yell real loud",
        "Method":"POST",
        "Href":"http://cats/123",
        "Title":"Scare the cat"
    }]
}