Action links for state transitions in Rest API - Step-by-Step Execution

Concept Flow - Action links for state transitions

Client requests resource

↓

Server sends resource with state and action links

↓

Client reads current state

↓

Client chooses an action link

↓

Client sends request to action link

↓

Server processes action and updates state

↓

Server responds with new state and updated action links

↓

Repeat or End

The client gets a resource with links to possible actions. It picks a link to change state. The server updates and sends back new state and links.

Execution Sample

Rest API

GET /order/123
Response:
{
  "state": "pending",
  "actions": {
    "pay": "/order/123/pay",
    "cancel": "/order/123/cancel"
  }
}

Client requests an order resource and receives its current state and links to possible actions.

Execution Table

Step	Client Action	Request Sent	Server Response	State After	Available Action Links
1	Request order resource	GET /order/123	{"state":"pending","actions":{"pay":"/order/123/pay","cancel":"/order/123/cancel"}}	pending	pay, cancel
2	Choose to pay	POST /order/123/pay	{"state":"paid","actions":{"ship":"/order/123/ship"}}	paid	ship
3	Choose to ship	POST /order/123/ship	{"state":"shipped","actions":{}}	shipped	none
4	Try to cancel after shipped	POST /order/123/cancel	{"error":"Action not allowed in current state"}	shipped	none

💡 No more valid actions after shipped state; cancel action rejected.

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4
state	none	pending	paid	shipped	shipped
available_actions	none	pay, cancel	ship	none	none

Key Moments - 3 Insights

Why can't the client cancel the order after it is shipped?

Because after step 3, the server response shows no 'cancel' action link available (see execution_table row 3). The client must follow only the provided action links.

How does the client know what actions are allowed next?

The server includes 'actions' links in each response (see execution_table rows 1-3). The client reads these links to decide the next valid action.

What happens if the client tries an action not in the links?

The server responds with an error message and does not change the state (see execution_table row 4). The client must only use provided action links.

Visual Quiz - 3 Questions

Look at the execution_table, what is the state after the client chooses to pay (step 2)?

A pending

B shipped

C paid

D cancelled

💡 Hint

Check the 'State After' column in row 2 of the execution_table.

At which step does the server stop providing any action links?

A Step 3

B Step 1

C Step 2

D Step 4

💡 Hint

Look at the 'Available Action Links' column in the execution_table rows.

If the client tried to ship the order before paying, what would likely happen?

A Server accepts and changes state to shipped

B Server rejects because 'ship' link is not provided yet

C Server cancels the order

D Server ignores the request silently

💡 Hint

Refer to how the server only allows actions from provided links (see execution_table step 4).

Concept Snapshot

Action links in REST APIs guide clients on allowed state changes.
Server responses include current state and URLs for next actions.
Clients must follow these links to change state.
Trying actions not linked results in errors.
This keeps client and server in sync about valid transitions.

Full Transcript

In REST APIs, servers send resources with current state and action links. Clients read these links to know what they can do next. For example, an order in 'pending' state might have 'pay' and 'cancel' links. When the client chooses 'pay', it sends a request to that link. The server updates the order to 'paid' and sends back new links like 'ship'. If the client tries an action not linked, the server rejects it. This way, the client always knows valid next steps and the server controls state changes safely.

Practice

1. What is the main purpose of action links in REST APIs for state transitions?

easy

A. To format the API response as JSON

B. To store data permanently on the server

C. To authenticate users before accessing the API

D. To provide URLs that clients can use to change the current state

Solution

1. Step 1: Understand what action links represent

   Action links are URLs included in API responses that show possible next steps or actions a client can take to change the state.

2. Step 2: Identify the purpose of action links

   They guide clients on how to move from one state to another by calling these URLs.

3. Final Answer:

   To provide URLs that clients can use to change the current state -> Option D

4. Quick Check:

   Action links = URLs for state change [OK]

Hint: Action links = URLs for next steps in state [OK]

Common Mistakes:

• Confusing action links with authentication tokens
• Thinking action links store data
• Assuming action links format data

2. Which of the following is the correct way to include an action link for a "cancel" operation in a REST API JSON response?

easy

A. "cancel": "POST https://api.example.com/orders/123/cancel"

B. "actions": {"cancel": "https://api.example.com/orders/123/cancel"}

C. "cancel_url": "https://api.example.com/orders/123/cancel"

D. "cancel_link": "GET https://api.example.com/orders/123/cancel"

Solution

1. Step 1: Recognize common pattern for action links

   Action links are often grouped under an "actions" key with action names as keys and URLs as values.

2. Step 2: Check each option's format

   "actions": {"cancel": "https://api.example.com/orders/123/cancel"} correctly uses an "actions" object with "cancel" as key and the URL as value, which is a clear and common pattern.

3. Final Answer:

   "actions": {"cancel": "https://api.example.com/orders/123/cancel"} -> Option B

4. Quick Check:

   Action links grouped under "actions" = "actions": {"cancel": "https://api.example.com/orders/123/cancel"} [OK]

Hint: Group action links under "actions" key for clarity [OK]

Common Mistakes:

• Using HTTP method inside the URL string
• Not grouping actions under a common key
• Using incorrect HTTP method for cancel

3. Given this JSON response snippet from a REST API:

{
  "state": "pending",
  "actions": {
    "approve": "https://api.example.com/items/42/approve",
    "reject": "https://api.example.com/items/42/reject"
  }
}

What will happen if the client calls the URL in the "approve" action link?

medium

A. The item state will change to approved

B. The item will be deleted

C. The client will receive an error because the URL is invalid

D. The item state will remain pending

Solution

1. Step 1: Understand the meaning of the "approve" action link

   The "approve" link is provided as a next step to change the state from "pending" to "approved" by calling that URL.

2. Step 2: Predict the effect of calling the approve URL

   Calling the approve URL triggers the state transition to "approved" as intended by the API design.

3. Final Answer:

   The item state will change to approved -> Option A

4. Quick Check:

   Calling "approve" URL = state changes to approved [OK]

Hint: Action link name hints the state change [OK]

Common Mistakes:

• Assuming the URL deletes the item
• Thinking the URL is invalid
• Believing state stays the same after action

4. A REST API response includes this action link:

"actions": {"complete": "https://api.example.com/tasks/99/complete"}

But calling this URL returns a 405 Method Not Allowed error. What is the most likely cause?

medium

A. The task with ID 99 does not exist

B. The URL is misspelled in the response

C. The client used GET instead of POST to call the action link

D. The server is down

Solution

1. Step 1: Understand 405 Method Not Allowed error

   This error means the HTTP method used is not supported by the URL endpoint.

2. Step 2: Identify common cause with action links

   Action links for state changes usually require POST, but clients often call them with GET by mistake.

3. Final Answer:

   The client used GET instead of POST to call the action link -> Option C

4. Quick Check:

   405 error = wrong HTTP method used [OK]

Hint: Use POST for action links, not GET [OK]

Common Mistakes:

• Assuming URL is misspelled without checking
• Thinking 405 means resource missing
• Blaming server downtime without evidence

5. You want to design a REST API for an order system with states: new, paid, shipped, and cancelled. Which of the following JSON responses best uses action links to guide clients through valid state transitions when the order is in paid state?

hard

A. {
"state": "paid",
"actions": {
"ship": "https://api.example.com/orders/555/ship",
"cancel": "https://api.example.com/orders/555/cancel"
}
}

B. {
"state": "paid",
"actions": {
"pay": "https://api.example.com/orders/555/pay",
"cancel": "https://api.example.com/orders/555/cancel"
}
}

C. {
"state": "paid",
"actions": {
"new": "https://api.example.com/orders/555/new",
"cancel": "https://api.example.com/orders/555/cancel"
}
}

D. {
"state": "paid",
"actions": {
"ship": "https://api.example.com/orders/555/ship",
"pay": "https://api.example.com/orders/555/pay"
}
}

Solution

1. Step 1: Identify valid next states from "paid"

   From "paid", the order can be "shipped" or "cancelled" but not "pay" or "new" again.

2. Step 2: Check which options provide correct action links

   { "state": "paid", "actions": { "ship": "https://api.example.com/orders/555/ship", "cancel": "https://api.example.com/orders/555/cancel" } } correctly offers "ship" and "cancel" actions, matching valid transitions.

3. Final Answer:

   JSON with "ship" and "cancel" actions for "paid" state -> Option A

4. Quick Check:

   Valid next actions for "paid" = ship, cancel [OK]

Hint: Only include valid next states as action links [OK]

Common Mistakes:

• Including actions that repeat previous states
• Missing valid next state actions
• Confusing state names with action names