# 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:
1. Add beanstalk to your list of dependencies in `mix.exs`:
def deps do
[{:beanstalk, "~> 0.1.0"}]
end
2. Ensure beanstalk is started before your application:
def application do
[applications: [:beanstalk]]
end
3. 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 <a href="doc/index.html">documentation for full details</a> 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<br>
✓ Release (require tests)<br>
✓ Repository<br>
✓ User
The following need coverage:
✗ Account<br>
✗ Code Reviews (Comments, Events, Assignees, Watchers, Settings)<br>
✗ Comment<br>
✗ Feed Key<br>
✗ Invitation<br>
✗ Integration<br>
✗ Node<br>
✗ Public Key<br>
✗ Repository Import<br>
✗ Permissions<br>
✗ Plan<br>
✗ Release Server<br>
✗ Server Environment<br>
✗ Team<br>
