Simpler way to get state of most recent workflow

[lucas42]

I'd like to know the state of the most recent workflow for each of my projects.

The only way I can figure out how to do this right now is:

1. GET /project/:project_slug/pipeline and parse out items[0].id (assuming the first item is the most recent - that's not entirely clear in the docs)
2. GET /pipeline/:pipeline_id and parse out workflows.ids[0] (The fact that ids is an array, but so far I've only ever seen a single value in it, suggests there's a level of potential complexity here that I don't understand)
3. GET /workflow/:workflow_id and parse out status (This bit is feels intuitive as it uses the same language as the UI)

Whilst this may work, I have a couple of problems with doing it that way:

• It requires 3 separate calls to the API, none of which can be done in parallel as they rely on data from the previous call.
• It introduces the concept of "pipelines" which really aren't clear to me. Even after reading https://circleci.com/blog/coming-soon-a-preview-on-pipelines/ I'm none the wiser. I'd rather stick with words that I'm familiar with from the UI, eg "projects", "workflows" and "jobs" (though in this case, jobs are too granular for what I care about)

Can I suggest a new endpoint? For example: GET /project/:project_slug/workflows
It'd return an array of workflows, sorted by most recent first. Each workflow would be an object containing the data currently surfaced in /workflow/:workflow_id

This would allow a single call to be made for each project and I wouldn't have to get my head around new concepts just for navigating the API.

[ndintenfass]

Thanks for the feedback. The confusion about why workflows.ids is an array is also why pipelines might not make immediate sense. The issue is that it's valid to declare multiple workflows in a config, which will become more common now that we allow conditional workflows (and we hope to add other features later that will make having multiple workflows more useful). The pipeline is, effectively, the "envelope" or "request" that the workflow was received within. It's the pipeline that's aware of things like the trigger information, and it's the pipeline where the config itself is processed. The workflows declared in your config are then run, but we are exposing the pipeline because it prevents a situation where each workflow stands totally alone even if they are executed from the same triggering event. All of that said, I won't rule out shipping an endpoint that would directly list recent pipelines, but at the moment it's not slated for upcoming work. I suggest you add your vote to this idea, where we'll track general demand: https://ideas.circleci.com/ideas/CCI-I-680

[lucas42]

Aha, that makes sense. Thanks for the explanation! I've been meaning to look into conditional workflows, but haven't gotten round to it.

Based on that, I guess what I'm really after is a new field on /project/:project_slug/pipeline/ which exposes an overall status for each pipeline (ie "success" if all the workflows in the pipeline were successful, or "error" if any failed).

Is your ideas site a better place to ask for API enhancements than here?

[stevenharman]

Possibly related: I am looking for a way to determine if there are other running|queued|pending Workflows for a given Branch.

Why?

I'm attempting to build an Orb that helps avoid Stacking Deploys. I'd like two different, but related strategies:

1. Deboucing Workflows.

   Workflow A came in and started running. Then Workflow B came in after it. At some point in A's run, it hits the API to see if there are other Workflows behind it, and if so, cancel itself. For example, after A finishes running its build, lint, and test Jobs successfully, it runs a Job (from the Orb) that checks for other Workflows "behind it." If it sees one, it cancels b/c the later Workflow (B) will handle the deploy task and push out A's code.

2. Cancel intermediate Workflows.

   The current Workflow (A) is already underway, and we don't want to abort it b/c it's doing a deploy. Two more Workflows come in behind A, let's call them B and C. In this case don't really need B to run to completion (it doesn't need to run its deploy Job) b/c all of its changes will also be included in C, since C came in after B. So, we'd like to cancel the "intermediate" B.

In both strategies, we need to hit the API to fetch Workflows for the same branch, and filter them by status. And we need some way to determine those Workflows are "after" the current one. So far as I can tell, this isn't currently available in the API, nor in v2. Perhaps it could be added as per @lucas42's request here?