Question: shouldn't PUT /executions return executionIdentifier?

[yarikoptic]

ATM PUT /executions (why not PUT /execution?) returns a an Execution entry, which seems to not be aware of its own executionIdentifier... so I am a bit confused of the "flow" of information here. May be someone could show just on a silly example a typical flow for a simple execution, e.g. to get what is PUT and OUTPUT for each of the following commands for a typical simple execution

1. PUT /executions -- to initialize a new one
2. GET /executions -- what would it return
3. PUT /executions/{executionIdentifier}/play -- which is what I guess is needed to switch execution from "initialized" to actually running?

That would help to mentalize it all -- thank you very much in advance

[axlbonnet]

If i'm not mistaking PUT /executions does not exist, and you're talking about POST /executions.

Anyway, the flow is this one :

1. I submit a new execution on POST /executions with an Execution payload containing a pipelineIdentifier, a name, some inputValues (and an optional timeout). The platform returns the same Execution object with enriched information : the important identifier and the status. Depending on the platform, the status could be Initializing or Running.

2. I monitor the execution state with GET /executions/{executionIdentifier} which returns an actualized Execution object. I'm interested in its status evolution and i'm waiting for it to transition from Initializing --> Ready or from Running --> Finished

3. (Optional) If my execution is Ready, i call PUT /executions/{executionsIdentifier}/play to start it. It returns an Execution object whose status is Running and I must monitor it again until it is Finished (Step 2).

Other related methods that could be confusing :

• PUT /executions/{executionIdentifier} allow to modify an execution. This is limited as only the name and the timeout can be changed.
• GET /executions is an utility that allow to list all my executions.

[glatard]

Maybe we could relate to the documentation here: https://github.com/simon-dube/CARMIN-server

[axlbonnet]

We should at least put in the CARMIN-API repository README some basic documentation about a typical flow, in order to show the main features of the API.

Then we should also include some request examples, and if possible several complete workflows somewhere. First we'll check if we can do that in the OpenAPI document, and if swaggerHub can show them nicely. Otherwise we'll also put that in the main README.