Git Product home page Git Product logo

dayron's Introduction

Dayron

Build Status Deps Status Inline docs Coverage Status Twitter

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.

Installation

  1. Add Dayron to your list of dependencies in mix.exs:
def deps do
  [{:dayron, "~> 0.1"}]
end
  1. Ensure Dayron is started before your application:
def application do
  [applications: [:dayron]]
end
  1. Then run mix deps.get in your shell to fetch the dependencies.

Getting Started

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
end

Defining Models

With modules and structs

Dayron 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
end

Reusing Ecto Models

Dayron 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
end

Retrieving Data

Using the Repo

After 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
  end

Accepted data output

By default, Dayron expects resources endpoints to output a flat list of elements. For instance if you are using JSON, your endpoint should look like this:

  [ 
  	{ "name": "User 1", "id": 0},
  	{ "name": "User 2", "id": 1}, 
  	{ "name": "User 3", "id": 2} 
  ]

You can also use basic nested elements like this:

  {
  	"data": [ 
  		{ "name": "User 1", "id": 0},
  		{ "name": "User 2", "id": 1}, 
  		{ "name": "User 3", "id": 2} 
  	]
  }

However, if you are using more complex or specific data structures, you can override the Model.from_json_list/3 or Model.from_json/3 in your Model.

Generating modules

You 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

Extra Configuration

Request Headers

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"]

HTTP Client Adapter

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: MyDayronAdapter

Important links

Contributing

Pull 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!

Building docs

$ MIX_ENV=docs mix docs

Contact Us

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 and License

Copyright (c) 2016, Inaka.

Dayron source code is licensed under the Apache 2 License.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.