Custom action in RESTful service

restful api
restful web services actions
"rest api" "actions"
rest api pagination standard
rest api methods
rest api operations on resources
rest api side effects
rest api design

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

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"
    }]
}

Custom action in RESTful service, 1) Should we use api/article/{id}/{action} since a lot of backend logic can happen there like pushing to remote locations or change of multiple properties. Probably � Create a custom action. This section describes how to build a custom control using the Nintex Workflow SDK. In Nintex Workflow, a workflow action represents the combination of a SharePoint workflow activity and a Nintex Workflow workflow action adapter. Configuration pages, included with the workflow action adapter, provide an interface with which a user can configure the workflow action.


for pure Restful Design i'd recommend something like:

POST /cats/123/actions

with the body of (the type of action is defined in request :

{
    "actionType": "jump",
    "customActionParameter": "some value"
}

but this will be a overkill. so i found it easier to follow Google Api Design Guide for Custom Methods:

POST /cats/123:jump

this is the method google uses in it's cloud infrastructure Api

RESTFul: state changing actions, Learn how to add custom actions to the Azure REST API. This article will walk through the requirements and best practices for endpoints that� The describe for the RESTful web service allows you to identify the shape and actions allowed on an ADF RESTful web service. It returns a JSON object that contains the attributes, actions, and links defined in the REST resource definition. The ADF REST framework supports the following describe use cases for the service end point:


Don't conflate the HTTP Verbs with your domain's state machine transitions or actions.

Stripe's invoice workflow provides a great example of how to represent state transitions or domain actions in a restful manner.

A action on your domain model could well be represented by a modification (PUT or PATCH) to a state or status field that would trigger workflows within your own code's state machine. For instance, in your example the jump action could also result in the same state as 3x steps, so it could be a modification to a height or altitude field. Your code would then likely implement some type of workflow management or state machine, and then you could emit your own events and validation rules based on the requested state changes, rather than based on the 'actions' performed to achieve it.

Adding custom actions to Azure REST API, The “actions” sub-collection can be seen as a command queue to which new action can be POSTed, that are then executed by the API. Each action resource that� Actions¶. Sometimes, it is required to expose an operation in the API that inherently is non RESTful. One example of such an operation is where you want to introduce a state change for a resource, but there are multiple ways in which the same final state can be achieved, and those ways actually differ in a significant but non-observable side-effect.


Methods - Thoughts on RESTful API Design, Like any RESTful API, the Actions Management API makes its services available to client Some of the actions in this example response are custom actions: The HTTP verbs comprise a major portion of our “uniform interface” constraint and provide us the action counterpart to the noun-based resource. The primary or most-commonly-used HTTP verbs (or methods, as they are properly called) are POST, GET, PUT, PATCH, and DELETE.


Actions Management REST-Based API, Use the loadActionSchema method in the API Actions Management REST-based API documentation to return the schemas for all actions available to a Services� Create custom APIs you can call from Azure Logic Apps. 05/26/2017; 14 minutes to read +3; In this article. Although Azure Logic Apps offers hundreds of connectors that you can use in logic app workflows, you might want to call APIs, systems, and services that aren't available as connectors.


Creating Custom Actions for Your APIs, What you trying to do is RPC its not REST service. Here you could And I think custom action also makes back-end API design and test easier. REST services provide a uniform interface using standard HTTP operations (such as GET, POST, PUT…) and exchange representations of resources. JSON and XML are frequently used formats in REST services. So, I would like to document it here and let you know the same so that it will stay as a reference to everyone.