Action links for state transitions in Rest API

Introduction

Action links help users or programs know what steps they can take next in a process. They make it easy to move from one state to another in a clear way.

When building an API that guides users through a process, like ordering or registration.

When you want to show what actions are possible after a certain event, like approving or rejecting a request.

When you want to make your API self-explanatory by including links to next steps.

When you want to avoid hardcoding URLs and let clients discover actions dynamically.

When you want to improve user experience by showing clear next steps in a workflow.

Syntax

Rest API

{
  "state": "current_state",
  "actions": {
    "action_name": {
      "href": "URL_to_perform_action",
      "method": "HTTP_method",
      "type": "content_type"
    },
    ...
  }
}

The actions object lists possible next steps with their URLs.

Each action includes the HTTP method to use (GET, POST, etc.) and the content type expected.

Examples

This example shows two possible actions from the "pending" state: approve or cancel the order.

Rest API

{
  "state": "pending",
  "actions": {
    "approve": {
      "href": "/orders/123/approve",
      "method": "POST",
      "type": "application/json"
    },
    "cancel": {
      "href": "/orders/123/cancel",
      "method": "POST",
      "type": "application/json"
    }
  }
}

Here, the only action from the "shipped" state is to track the shipment using a GET request.

Rest API

{
  "state": "shipped",
  "actions": {
    "track": {
      "href": "https://tracking.example.com/track/123",
      "method": "GET",
      "type": "text/html"
    }
  }
}

Sample Program

This simple Flask API returns the current state of an order and the possible actions as links. It shows how action links guide the client on what to do next.

Rest API

from flask import Flask, jsonify, request

app = Flask(__name__)

orders = {
    1: {"state": "pending"},
    2: {"state": "shipped"}
}

@app.route('/orders/<int:order_id>', methods=['GET'])
def get_order(order_id):
    order = orders.get(order_id)
    if not order:
        return jsonify({"error": "Order not found"}), 404

    state = order['state']
    if state == 'pending':
        actions = {
            "approve": {
                "href": f"/orders/{order_id}/approve",
                "method": "POST",
                "type": "application/json"
            },
            "cancel": {
                "href": f"/orders/{order_id}/cancel",
                "method": "POST",
                "type": "application/json"
            }
        }
    elif state == 'shipped':
        actions = {
            "track": {
                "href": f"https://tracking.example.com/track/{order_id}",
                "method": "GET",
                "type": "text/html"
            }
        }
    else:
        actions = {}

    return jsonify({"state": state, "actions": actions})

if __name__ == '__main__':
    app.run(debug=True)

Important Notes

Action links help keep your API flexible and easy to use.

Always include the HTTP method so clients know how to use the link.

Use clear and consistent naming for actions to avoid confusion.

Summary

Action links show what steps are possible next in a process.

They include URLs, HTTP methods, and content types for each action.

This makes APIs easier to understand and use without guesswork.