httpoison_form_data

A library for building Multipart and URLEncoded structures from Elixir structures for HTTPoison and Hackney.


License
MIT

Documentation

FormData

A library for formatting data to be used with HTTPoison and Hackney.

This library was originally written to help with formatting data to upload files for internal Spiceworks projects, but has expanded to include formatting all multipart data for POST requests to work with HTTPoison and Hackney, in addition to formatting url encoded requests for POST and GET, both with the supported HTTPoison syntax and with a string to append to any URL.

Installation

Add httpoison_form_data to your list of dependencies in mix.exs:

def application do
  [applications: [:httpoison]]
end

def deps do
  [{:httpoison_form_data, "~> 0.1"},
   {:httpoison, "~> 1.0"}]
end

Usage

The outermost layer in your nested structure MUST be a map, keyword list, or struct.

Multipart Requests

# This structure will be used in the following example
some_structure = %{
  first_key: "first_value",
  second_key: [
    "second_value",
    "third_value",
    %{
      third_key: "fourth_value",
      fourth_key: {
        "fifth_value",
        "sixth_value"
      }
    }
  ],
  fifth_key: FormData.File.new("path/to/file.txt")
}

Example 1

with {:ok, payload} <- FormData.create(some_structure, :multipart),
  do: HTTPoison.post("some.url/", payload)

# The above code produces the following request
HTTPoison.post("some.url/", {
  :multipart,
  [
    {"", "first_value", {"form-data", [{"name", "\"first_key\""}]}, []},
    {"", "second_value", {"form-data", [{"name", "\"second_key[]\""}]}, []},
    {"", "third_value", {"form-data", [{"name", "\"second_key[]\""}]}, []},
    {"", "fourth_value", {"form-data", [{"name", "\"second_key[][third_key]\""}]}, []},
    {"", "fifth_value", {"form-data", [{"name", "\"second_key[][fourth_key][]\""}]}, []},
    {"", "sixth_value", {"form-data", [{"name", "\"second_key[][fourth_key][]\""}]}, []},
    {:file, "path/to/file.txt", {"form-data", [{"name", "\"fifth_key\""}, {"filename", "\"file.txt\""}]}, []}
  ]
})

URL Encoded Requests

# This structure will be used in the following examples
other_structure = %{
  one: "two",
  three: "four"
}

Example 2

with {:ok, payload} <- FormData.create(other_structure, :url_encoded),
  do: HTTPoison.post("some.url/", payload)

# The above code produces the following request
HTTPoison.post("some.url/", {
  :form,
  [
    {"one", "two"},
    {"three", "four"}
  ]
})

Example 3

with {:ok, payload} <- FormData.create(other_structure, :url_encoded, get: true),
  do: HTTPoison.get("some.url/", %{}, payload)

# The above code produces the following request
HTTPoison.get("some.url/", %{}, params: [
  {"one", "two"},
  {"three", "four"}
])

Notes

Although the examples do not show this, url_encoded formdata supports nested structures the same as multipart, but will ignore any %FormData.File{} structs, since url_encoded requests do not support file uploads.

Contributors

Lincense

Copyright © 2016 Spiceworks, Inc.

This work is free. You can redistribute it and/or modify it under the
terms of the MIT License. See the LICENSE file for more details.