Inconsistency between workflow docs and api v2 workflow docs

API
1

The workflow documentation talks about state:
https://circleci.com/docs/2.0/workflows/#states
but the API docs talks about status
https://circleci.com/docs/2.0/workflows-overview/#possible-workflow-statuses
and the payloads indeed contain a property named status. The workflows docs should be aligned.

2

Hello @gempain,

Thanks for reporting this inconsistency, I’ve raised a request with our Docs team to get this updated!

3

@ScottW hey there, thanks for the feedback ! Sorry for being so sharp in my posts, I was integrating your API today and wanted to quickly write down some issues I’ve found. Something bugs me in your v2 API, why do you use the pipeline number in certain endpoints and the pipeline ID in others ?

  • You get a pipeline (https://circleci.com/docs/api/v2/#get-a-pipeline) by its number while you get pipeline workflows (https://circleci.com/docs/api/v2/#get-a-pipeline-39-s-workflows) using the pipeline ID. That’s confusing IMO.
  • Pipelines don’t have a status, they have a state which does not tell anything about whether the workflows of a pipeline have succeded
  • The notify property is not documented anywhere, I only found it because of a comment on this website, and I only saw a slight mention in the API v1 docs for getting a job, where it says

This is also the payload for the notification webhooks, in which case this object is the value to a key named ‘payload’

Regarding this notification, you do include information about the workflow (id, number etc) but not about the pipeline, and it is quite a hassle to walk up the model to get to the pipeline or a given job.

  • There’s a page for viewing all pipelines, but when you click the pipeline, you actually get to the workflow page. There’s no page that lists the workflows of a pipeline.
  • API v1 allowed to trigger a job using a project API token, which is readonly, and that’s a good pattern ! API v2 allows to trigger a pipeline using parameters, but you must use a personal access token, and that’s not so great IMO. If I leak a readonly token, that’s not as bad as if I leak a personal access token which gives full access to the API. Why couldn’t you use a project access token since the path to trigger the pipeline contains the project path ?

Sorry if it feels like I’m just listing things that don’t seem right, I could go one hours talking about those that are, but I’m really trying to focus on improvement :slight_smile:

Keep up the good work !