afaur / elixir-plug-api

Starter for working with Elixir, Plug, and Cowboy. Provides an example of how to use a compiled eex template for a route. Has one API route with a test that validates it. Uses HTTPoison for testing a remote web request. Uses Poison for JSON encoding an API response. See `with_new_relic_agent` branch for an example of using new relic monitoring. Has code comments and getting started guide in readme.

Project Overview

• Exposes one GET route
  • GET /api/users returns 200 OK result of ["Mary", "John", "Jill"]
• Includes e2e test to check that the endpoint responds correctly
• Uses four dependencies
  • Cowboy
    • Small Fast Http2 / Websocket Server
  • Plug
    • Middleware / Composable Modules
  • Poison
    • JSON Encoding / Decoding
  • HTTPoison
    • Testing Endpoints (Elixir CURL / Fetch)
    • Uses binaries instead of string lists
  • These deps do have sub deps
    • Goal is to minimize dep reliance as much as possible
• See with_env_config branch which adds a make config task for creating .env from a .env_sample.
• See with_new_relic_agent branch for an example of new relic monitoring.
• See with_new_relic_agent_and_env_config branch for an example that combines the two individual branches together.

Organization

• Uses a .lab folder, a Makefile, and a Justfile
  • .lab contains all mix new generated files / folders
  • Uses symlinks to / from .lab to simplify organization
  • Has a Makefile and Justfile to manage project commands

Laboratory Folder

• Allows important folders / files to stay in the primary project dir
  • .lab folder is short for laboratory (where we mix our elixir :D)
    • src folder is linked to the lib folder in .lab
    • conf folder contains both the:
      • mix.exs from the root of .lab folder
      • config.exs from the config dir of .lab folder
    • test folder is linked to the test folder in .lab

Install Elixir

• OSX
• Linux
• Windows

Using Make / Just

• This project uses Make or Just to simplify mix and iex commands
• If using just, replace all commands starting with make to just

Installing Make / Just

• Having either one on your machine will work and setup is easy
  • OSX / Linux
    • By default you should already have make on your machine
    • If you want to install just you can get it here
      • Just Github Repository
    • On OSX you can run brew install just
  • Windows
    • Make doesn't come by default
      • Using Make On Windows
    • If you want to install just you can get it here
      • Just Github Repository

Install Dependencies

• make deps
  • See code in conf/mix.exs

Build Project

• make build
  • See code in conf/*.exs

Running Project

• Start the server
  • make run
• See code in src/*.ex

Testing

• How to test either manually or automatically

Manual Testing

• After running make run you can either:
  • Use CURL
    • curl -v "http://127.0.0.1:8085/api/users"
  • Use Browser
    • open http://127.0.0.1:8085/api/users

Automatic Testing

• ExUnit
  • make test
    • Runs project and asserts correct response is returned
    • See code in test/http_app_test.ex