starting down the road to supporting the circleci api v2

[maplebed]

In doing some work with the CircleCI API I got a suggestion that I look at v2 of the API. It is not yet released but some of the pre-release documentation is https://github.com/CircleCI-Public/api-preview-docs. Specifically, https://github.com/CircleCI-Public/api-preview-docs/blob/master/docs/api-changes.md holds the definition for the /workflow endpoint.

This change adds support for v2 of the API by initially adding the ability to fetch details for a specific workflow and all the jobs in that workflow. From there you can fall back to the v1 api to get the full details for a specific job.

I'm opening this PR for comments on the approach. Is this useful work? If it is, maybe it could be merged in to a v2 tag or something for further work before landing in master, since the API is still in pre-release mode and will likely change.

Thanks!

Here's some sample code that exercises the new functions defined: https://gist.github.com/maplebed/d9cb97961448dc02a641200b089e2f19

[jszwedko]

Apologies for the delay in reviewing this! I have been thinking about it this week in terms of the best way to add support for v2 of Circle's API.

I'll write more tomorrow, but I definitely support this addition. I'm currently thinking that this library can abstract over the differences in API versions. Basically that we could drop the V2 from these method names (but call in in the doc comments that they are subject to change given their "cutting edge" nature).

[maplebed]

Thanks for the review and comments! I am on board with making the version of the api hit to serve data abstracted out. The first problem I hit trying it out that way was that frustratingly, the two versions use the same name (eg workflow) for different data structures. I’m not sure what the right way out of that pickle looks like taking in to account backwards compatibility. Anyway :100: finding a good solution and letting the library take away some of the work from the users of the library.

[jszwedko]

Ah, yes, I neglected that Workflow is also an entity returned by the v1 API though seemingly would be dropped eventually with the idea of a Build being removed in-lieu of pipeline. Perhaps we could still keep V2 in the struct name for that, but still remove V2 from the method name.

[glenjamin]

I can say that the final V2 API will likely have a heirarchy of Project -> Pipeline -> Workflow -> Job.

There are also plans to publish an accurate OpenAPI Schema, which may make your lives easier.

[jberryfs]

Any updates on this? Deciding if I should build on this or how to approach v2 usage myself.

[jszwedko]

Hi @jberryfs,

Thanks for bumping this. To be honest, I haven't been using this library since I stopped using CircleCI as much though it should still work for the v1 API AFAIK. I'd be happy to promote and link to a fork though if someone wants to pick up the mantle.

[TomTucka]

Hey @jszwedko,

I sent you an email about this! I'd be up for taking on this as an open-source project, I'm keen to get this moving so we can support the v2 API.