Beanstalk-Elixir
An HTTP client for the Beanstalk API written in Elixir.
Beanstalk is for hosting and deployment of code: https://beanstalkapp.com
The API documentation can be found here: http://api.beanstalkapp.com
Installation
It’s available on Hex.pm, so it can be installed by:
Add beanstalk to your list of dependencies in
mix.exs
:def deps do [{:beanstalk, "~> 0.1.0"}] end
Ensure beanstalk is started before your application:
def application do [applications: [:beanstalk]] end
In your
config/config.exs
, add the following and set your Beanstalk settings:config :beanstalk, account: "account-name", username: "username", password: "password"
The account
is the sub-domain you use to access Beanstalk. If the URL is http://company.beanstalkapp.com
, then your account is company
.
The username
and password
are the user account you want to use to access the API.
It’s advisable to create an account specifically for using the API, and set the access levels you require for your needs instead of using your own account.
Making calls
Firstly, start the module, and then call the end-point…
{:ok, response} = Beanstalk.User.all
{:ok,
[%{"user" => %{
"account_id" => 123456,
"admin" => false,
"can_create_repos" => false,
"created_at" => "2016/07/10 12:50:25 +1000",
"email" => "test@test.com",
"first_name" => "Test",
"id" => 654321,
"last_name" => "Test",
"login" => "fake-username",
"name" => "Test Test",
"owner" => true,
"timezone" => "Melbourne",
"updated_at" => "2016/07/23 16:37:11 +1000"
}
}
]}
See the documentation for full details of all the end-points.
Handling responses
The core Beanstalk
module handles the response, so you don’t have to worry about HTTP status codes, JSON decoding or error trapping - that’s all done for you.
All you need to do is pattern match the following tuples.
Successful response
The most common response is the successful one…
{:ok, response} => ...
:ok
indicates a successful call.
response
is the result body, decoded from JSON (using JSX.decode
) to a Map.
Empty (but successful) response
This will only occur when calling an end-point that uses update
or delete
.
This is because the body of the response will be empty - but it’s still a successful response.
{:ok, :empty} => ...
:ok
indicates a successful call.
:empty
indicates an empty body.
Failure response
In the case the call fails, by means of bad parameters or bad response:
{:error, message} => ...
:error
indicates an error occurred making the call.
message
is a string containing all of the error messages returned by Beanstalk.
As an aside…
All of the end-point modules rely on the core Beanstalk
module, and it’s unlikely you’ll ever call the Beanstalk
module directly (unless of course you want to contribute?).
As the Beanstalk
module uses HTTPoison
, the generated documentation quickly became confusing and added nothing to this module.
So whilst it’s core of this plugin, documentation for it has been disabled - but it is commented.
Any ideas, pull requests or feedback welcome.
Coverage
The following end-points are covered with documentation:
✓ Changeset
✓ Release (require tests)
✓ Repository
✓ User
The following need coverage:
✗ Account
✗ Code Reviews (Comments, Events, Assignees, Watchers, Settings)
✗ Comment
✗ Feed Key
✗ Invitation
✗ Integration
✗ Node
✗ Public Key
✗ Repository Import
✗ Permissions
✗ Plan
✗ Release Server
✗ Server Environment
✗ Team