View Source CircleCI API Client for Elixir
The ergonomics of a hand-crafted client with the API coverage of generated code.
This library uses an OpenAPI Code Generator that has the flexibility to wrangle the generated code into an ergonomic client.
Furthermore, this library has no opinions about what you use for HTTP requests, serialization, etc. Instead it allows users to define their own stack of plugins, many of which are provided here.
Installation
This library is available on Hex.pm.
Add the dependency in mix.exs
:
def deps do
[
{:circleci_client, "~> 0.1.0"}
]
end
Then install the dependency using mix deps.get
.
Configuration
This library comes with a common default set of configuration.
To use it successfully, you will need to install HTTPoison
and Jason
.
(Remember, these libraries can easily be switched out by changing the stack
configuration.
See CircleCI.Config
for more information.)
Some good up-and-running configuration to set:
app_name
will include the name of your application in the User Agent so CircleCI can contact you if they notice any problems.
config :circleci,
app_name: "MyApp"
For more information about configuration, see the documentation for CircleCI.Config
.
Usage
All of the client operations are generated based on the OpenAPI description provided by CircleCI. In general, you can expect to find:
CircleCI.Resource.operation(path1, path2, ..., body, opts)
Where:
Resource
is the name of the resource as tagged by CircleCI, likeWorkflow
.operation
is the name of the route, likeget
orget_workflow_by_id
.- The first arguments are path parameters, such as
workflow_id
in/workflow/{workflow_id}
. - If the request accepts a body, then there will be a
body
parameter. - Finally, all operations accept a keyword list of options.
The options accepted by operations may differ depending on your chosen stack. However, the following are always available:
auth
(string or struct implementingCircleCI.Auth
) Credentials to use for the request.server
(URL including scheme) Base API server to use, such ashttps://circleci.com/api/v2
.
Whenever CircleCI specifies a named schema as the response type for an operation, an Elixir struct will be returned.
Note that some schemas have been collapsed into a single struct (like CircleCI.Workflow
) where not all of the fields may be filled in.
However, responses are still properly typed by their type specifications.
Contributing
Because this library uses a code generator for the majority of its mass, there are two modes of contribution. Please consider these when creating issues or opening pull requests:
- If the generated code is out of date, the fix may be as simple as running
mix gen.api
using the latest OpenAPI description. - If the client isn't working as expected, the fix may be more involved and require careful thought and versioning.
For more on what this means to you as a contributor, please see the contribution guidelines.