Dayron is a flexible library to interact with RESTful APIs and map resources to Elixir data structures. It works similar of Ecto.Repo but, instead of retrieving data from a database, it has underlying http clients to retrieve data from external HTTP servers.
- Add Dayron to your list of dependencies in
mix.exs:
def deps do
[{:dayron, "~> 0.1"}]
end- Ensure Dayron is started before your application:
def application do
[applications: [:dayron]]
end- Then run
mix deps.getin your shell to fetch the dependencies.
Dayron requires a configuration entry with at least the external url attribute:
# In your config/config.exs file
config :my_app, MyApp.RestRepo,
url: "http://api.example.com"Then you must define MyApp.RestRepo somewhere in your application with:
# Somewhere in your application
defmodule MyApp.RestRepo do
use Dayron.Repo, otp_app: :my_app
endDayron Models are simple modules with use Dayron.Model to implement the required protocol. The resource option defines the path to be used by the HTTP client to retrieve data. A struct must be defined with defstruct to allow json responses mapping.
defmodule MyApp.User do
# api requests to http://api.example.com/users
use Dayron.Model, resource: "users"
# struct defining model attributes
defstruct name: "", age: 0
endDayron Models can work together with Ecto Models, allowing data loading from Database and External APIs just selecting the desired Repo. The defined schema will be used by Dayron when parsing server responses. If no resource option is present, the schema source is used as resource name.
defmodule MyApp.User do
use Ecto.Schema
use Dayron.Model
# dayron requests to http://api.example.com/users
schema "users" do
field :name, :string
field :age, :integer, default: 0
end
endAfter defining the configuration and model, you are allowed to retrieve data from an external API in a similar way when compared to an Ecto Repo. The example below presents a UsersController where an index action retrieves a list of users from the server, and a show action retrieves a single User:
defmodule MyApp.UsersController do
use MyApp.Web, :controller
alias MyApp.User
alias MyApp.RestRepo
def index(conn, params)
conn
|> assign(:users, RestRepo.all(User))
|> render("index.html")
end
def show(conn, %{"id" => id}) do
case RestRepo.get(User, id) do
nil -> put_status(conn, :not_found)
user -> render conn, "show.html", user: user
end
endYou can generate Dayron modules using the task dayron.gen.model
mix dayron.gen.model User users name age:integer
The first argument is the module name followed by the resource path. The generated model will contain:
- a model file in lib/your_app/models
- a test file in test/your_app/models
Both the model and the test path can be configured using the Dayron generators
config.
config :dayron, :generators,
models_path: "web/models",
models_test_path: "test/models"The model fields are given using name:type syntax
where types can be one of the following:
:array, :integer, :float, :boolean, :string
Omitting the type makes it default to :string
Using the configuration you're allowed to set headers that will be sent on every HTTP request made by Dyron. In the configuration example below, the access-token header is sent on every request:
# In your config/config.exs file
config :my_app, MyApp.Dayron,
url: "https://api.example.com",
headers: ["access-token": "my-api-token"]Currently the only adapter available is HTTPoisonAdapter, which uses HTTPoison and hackney to manage HTTP requests.
You can also create your own adapter implementing the Dyron.Adapter behavior, and changing the configuration to something like:
# In your config/config.exs file
config :my_app, MyApp.Dayron,
url: "https://api.example.com",
adapter: MyDayronAdapterPull request are very wellcome, but before opening a new one, please open an issue first.
If you want to send us a pull request, get the project working in you local:
$ git clone https://github.com/inaka/Dayron.git
$ cd Dayron
$ mix deps.get
$ mix test
Create a branch with the issue name and once you're ready (new additions and tests passing), submit your pull request!
$ MIX_ENV=docs mix docs
If you find any bugs or have a problem while using this library, please open an issue in this repo (or a pull request).
You can also check all of our open-source projects at inaka.github.io.
Copyright (c) 2016, Inaka.
Dayron source code is licensed under the Apache 2 License.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent