Elixir library for the Upvest API.
In order to retrieve your API credentials for using this Go client, you'll need to sign up with Upvest.
If available in Hex, the package can be installed
by adding upvest
to your list of dependencies in mix.exs
:
def deps do
[
{:upvest, "~> 0.1.0"}
]
end
Alternatively, you can install the library by a particular commit reference:
def deps do
[
{:upvest, git: "https://github.com/rpip/upvest-elixir", ref: "commit ref here"}
]
end
Where possible, the services available on the client groups the API into logical chunks and correspond to the structure of the Upvest API documentation.
All tenancy related operations must be authenticated using the API Keys Authentication, whereas all actions on a user's behalf need to be authenticated via OAuth. The API calls are built along with those two authentication objects.
All API calls return either {:ok, response}
or {:error, error}
, and where possible succesful response are transformed into Elixir structs mapped to the corresponding Upvest API resource.
The Upvest API uses the notion of tenants, which represent customers that build their platform upon the Upvest API. The end-users of the tenant (i.e. your customers), are referred to as clients. A tenant is able to manage their users directly and is also able to initiate actions on the user's behalf (create wallets, send transactions).
alias Upvest.Client
alias Upvest.Authentication.KeyAuth
alias Upvest.Tenancy.User
keyauth = %KeyAuth{
api_key: your_api_key,
api_secret: your_api_secret,
api_passphrase: your_api_passphrase
}
client = Client.new(keyauth)
# create a user
with {:ok, user} <- User.create(client, username, password) do
# do something with new user created
else
{:error, error} ->
# handle the error
end
# list users
{:ok, users} = User.list(client)
# retrieve 200 users
{:ok, users} = User.list_n(client, 200)
# change password
{:ok, user} = User.change_password(client, username, current_password, new_password)
The authentication via OAuth allows you to perform operations on behalf of your user. For more information on the OAuth concept, please refer to our documentation. Again, please retrieve your client credentials from the Upvest account management.
Next, create a Client
with your Upvest OAuth in order to authenticate your API calls on behalf of a user:
alias Upvest.Client
alias Upvest.Authentication.OAuth
alias Upvest.Clientele.Wallet
oauth = %OAuth{
client_id: client_id,
client_secret: client_secret,
username: your_users_username,
password: your_users_password
}
# If you already have a client created with a key auth
# you can create a new oauth client from that by changing the auth param
client = %{client | auth: oauth}
# alternatively, client = Client.new(oauth)
with {:ok, wallet} <- Wallet.create(client, user_password, asset_id) do
# handle new wallet created
else
{:error, error} ->
# handle error
end
In case there is an error, the response is {:error, error} where error is one of:
- Upvest.APIConnectionError
- Upvest.AuthenticationError
- Upvest.InvalidRequestError
- Upvest.PermissionError
- Upvest.APIError
For example, using already taken username will return the error:
{:error,
%Upvest.APIError{
code: 409,
details: [
%{
"domain" => "clientele",
"location" => "username",
"locationType" => "parameter",
"message" => "Duplicate Value",
"reason" => "duplicateValue"
}
],
message: "User with given username exists already",
type: "api_error"
}}
$ MIX_ENV=docs mix docs
Clone the repo and fetch its dependencies:
$ git clone https://github.com/rpip/upvest-elixir
$ cd upvest-elixir
$ mix do deps.get, compile
$ mix test
-
Code must be nicely formatted:
mix format
-
All types, structs and functions should be documented.
-
Ensure that
mix test
succeeds. -
Set up config settings via environment variables, ideally in a .env file you can source:
# Set your tenancy API key information here. export API_KEY=xxxx export API_SECRET=xxxx export API_PASSPHRASE=xxxx # Set your OAuth2 client information here. export OAUTH2_CLIENT_ID=xxxx export OAUTH2_CLIENT_SECRET=xxxx
Run all tests:
mix test
Run a single test:
mix test test/wallet_test.exs
For a comprehensive reference, check out the Upvest documentation.
For details on all the functionality in this library, see the HexDocs documentation.