Why on earth do half of the APIs take a <RESOURCE>_number, and half work with an ID

Working with the API is mind bending-ly terrible.

Given a branch name, you want to find artifacts of a job, you can maybe use an insights API to query a branch… but you can’t get the VCS information, but then you discover there’s two get-pipeline APIs, one called get all pipelines which lets you filter by a branch, an somewhere along the way you switch from numbers to IDs, like good god people.!!! :slight_smile: Don’t mean to be too harsh, but surely something can be improved here.

To be more constructive.

I don’t think most end users think first of circle’s domain model. Instead all tooling is based on the VCS. Every resource should be queryable by VCS identifiers (branch, commit, tag, etc.). For instance, given a job_name and a commit, get all the artifacts.

There are some things that may bleed through, like the fact a job can run multiple times, and even succeed multiple times, for the same commit. And it’s great that you have APIs for diving into the details of what happened for a particular build.

IDs vs numbers, get rid of the distinction, pick one, or make both available on all APIs as the primary key.
All list endpoints take branch, sha, tag as filters.
Leaf resources have links back up the the tree, i.e. artifacts endpoint returns a list of “artifact producing runs”, which contain the list of artifacts, job id, workflow id, and pipeline id.


1 Like

Thank you for the clarification and reframing. I will pass this along to the API team and see if they have advice or helpful feedback!