StackStorm / StackStorm/st2

[Feature] API endpoints for ST sync execution

Open
#5,527 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Python
Stars
6.5k
Forks
787
PR merge metrics
No merged PRs in 30d

Description

Saw that issue:
https://forum.stackstorm.com/t/is-it-possible-to-execute-an-action-synchronously-with-the-api/99

So thought a good Async to sync ST execution can be in the following form.
concatenating sync/ for the relevant new endpoints.

Asynchronous Pattern:

With the asynchronous pattern, if the remote server indicates that the request is accepted for processing with a 202 (Accepted) response, we will have to keep polling a URL specified in the response's location header until reaching a terminal state.

This pattern specifies that after an HTTP action calls or sends a request to an endpoint, service, system, or API, the receiver immediately returns a "202 ACCEPTED" response. This code confirms that the receiver accepted the request but hasn't finished processing. The response can include a location header that specifies the URI and a refresh ID that the caller can use to poll or check the status for the asynchronous request until the receiver stops processing and returns a "200 OK" success response or other non-202 response.

So Once we are creating an execution (Should return 202 status code with the location URL):
curl -X POST -H 'Connection: keep-alive' -H 'Accept-Encoding: gzip, deflate' -H 'Accept: */*' -H 'User-Agent: python-requests/2.11.1' -H 'content-type: application/json' -H 'X-Auth-Token: da5ecf3b0ab841008d663052fe95cddd' -H 'Content-Length: 69' --data-binary '{"action": "core.local", "user": null, "parameters": {"cmd": "date"}}' http://127.0.0.1:9101/v1/sync/executions
The response can include a location header that specifies the URI.
I.E:
<HOST>/api/v1/sync/executions/{id}

Full URL for polling will be like (Getting ST execution) (Should return 202 status code until it has a final state and will return a "200 OK" success response):
curl -X GET -H 'Connection: keep-alive' -H 'Accept-Encoding: gzip, deflate' -H 'Accept: */*' -H 'User-Agent: python-requests/2.11.1' -H 'X-Auth-Token: da5ecf3b0ab841008d663052fe95cddd' http://127.0.0.1:9101/v1/sync/executions/58de117e49d4af083399181c

An HTTP 202 response should indicate the location and frequency that the client should poll for the response. It should have the following additional headers:

Header Description Notes
Location A URL the client should poll for a response status. This URL could be a SAS token with the Valet Key Pattern being appropriate if this location needs access control. The valet key pattern is also valid when response polling needs offloading to another backend
Retry-After An estimate of when processing will complete This header is designed to prevent polling clients from overwhelming the back-end with retries.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the existing execution API entry points alongside the proposed POST /v1/sync/executions and GET /v1/sync/executions/{id} endpoints. The work is complete when creation returns 202 with a Location and Retry-After header, polling remains 202 until a final state, and then returns 200 or another appropriate terminal response.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.