HTTPoison

https://hexdocs.pm/httpoison/
Admin
HTTPoison is an HTTP client library for Elixir that enables developers to make HTTP requests and...
Tokens:26,480
Snippets:179
Trust Score:9
Update:6 months ago
Show doc for...
Tokens:
Raw
### start()

Source: https://hexdocs.pm/httpoison/HTTPoison.html

Starts HTTPoison and its dependencies.

```APIDOC
## start()

### Description
Starts HTTPoison and its dependencies.

### Method
POST

### Endpoint
N/A

### Parameters
None

### Request Example
```elixir
:ok = Application.ensure_all_started(:httpoison)
```

### Response
#### Success Response (200)
- **status** (atom) - Indicates successful start, typically `:ok`.

#### Response Example
```elixir
:ok
```
```

--------------------------------

### Start HTTPoison and Make a GET Request

Source: https://hexdocs.pm/httpoison/readme.html

Start the HTTPoison client and make a GET request. Handles successful responses and connection errors.

```elixir
iex> HTTPoison.start
iex> HTTPoison.get! "https://postman-echo.com/get"
%HTTPoison.Response{
  status_code: 200,
  body: "{\n  \"args\": {},\n  \"headers\": {\n    \"x-forwarded-proto\": \"https\",\n    \"x-forwarded-port\": \"443\",\n    \"host\": \"postman-echo.com\",\n    \"x-amzn-trace-id\": \"Root=1-644624fb-769bca0458e739dc07f6b630\",\n    \"user-agent\": \"hackney/1.18.1\"\n  },\n  \"url\": \"https://postman-echo.com/get\"\n}",
  headers: [ ... ]
}
```

```elixir
iex> HTTPoison.get! "http://localhost:1"
** (HTTPoison.Error) :econnrefused
```

```elixir
iex> HTTPoison.get "http://localhost:1"
{:error, %HTTPoison.Error{id: nil, reason: :econnrefused}}
```

--------------------------------

### Start HTTPoison

Source: https://hexdocs.pm/httpoison/HTTPoison.html

Starts the HTTPoison service and its dependencies. This should typically be called when your application starts.

```elixir
start()
```

--------------------------------

### Start HTTPoison

Source: https://hexdocs.pm/httpoison/HTTPoison.Base.html

Starts the HTTPoison application.

```APIDOC
## Start HTTPoison

### Description
Starts the HTTPoison application.

### Method
Not applicable.

### Endpoint
Not applicable.

### Parameters
None

### Request Example
```elixir
HTTPoison.start()
```

### Response
#### Success Response
- **result** (list of atoms) - A list of started applications.

#### Error Response
- **error** (term) - An error term if the application fails to start.

#### Response Example
```elixir
{:ok, [:http_client, :ssl_verify_fun]}
{:error, :already_started}
```
```

--------------------------------

### Perform a GET request with HTTPoison

Source: https://hexdocs.pm/httpoison/HTTPoison.html

Example of issuing a synchronous GET request to a URL using the HTTPoison module.

```elixir
iex> HTTPoison.get!("https://api.github.com")
%HTTPoison.Response{status_code: 200,
                    headers: [{"content-type", "application/json"}],
                    body: "{...}"}
```

--------------------------------

### Perform HTTP requests

Source: https://hexdocs.pm/httpoison/index.html

Examples of GET and POST requests, including error handling and response inspection.

```elixir
iex> HTTPoison.start
iex> HTTPoison.get! "https://postman-echo.com/get"
%HTTPoison.Response{
  status_code: 200,
  body: "{\n  \"args\": {},\n  \"headers\": {\n    \"x-forwarded-proto\": \"https\",\n    \"x-forwarded-port\": \"443\",\n    \"host\": \"postman-echo.com\",\n    \"x-amzn-trace-id\": \"Root=1-644624fb-769bca0458e739dc07f6b630\",\n    \"user-agent\": \"hackney/1.18.1\"\n  },\n  \"url\": \"https://postman-echo.com/get\"\n}",
  headers: [ ... ]
}

iex> HTTPoison.get! "http://localhost:1"
** (HTTPoison.Error) :econnrefused
iex> HTTPoison.get "http://localhost:1"
{:error, %HTTPoison.Error{id: nil, reason: :econnrefused}}

iex> HTTPoison.post "https://postman-echo.com/post", "{\"body\": \"test\"}", [{"Content-Type", "application/json"}]
{:ok,
 %HTTPoison.Response{
   status_code: 200,
   body: "{\n  \"args\": {},\n  \"data\": {\n    \"body\": \"test\"\n  },\n  \"files\": {},\n  \"form\": {},\n  \"headers\": {\n    \"x-forwarded-proto\": \"https\",\n    \"x-forwarded-port\": \"443\",\n    \"host\": \"postman-echo.com\",\n    \"x-amzn-trace-id\": \"Root=1-6446255e-703101813ec2e395202ab494\",\n    \"content-length\": \"16\",\n    \"user-agent\": \"hackney/1.18.1\",\n    \"content-type\": \"application/json\"\n  },\n  \"json\": {\n    \"body\": \"test\"\n  },\n  \"url\": \"https://postman-echo.com/post\"\n}",
   headers: [ ... ]
 }}
```

--------------------------------

### Example usage of output

Source: https://hexdocs.pm/httpoison_form_data/FormData.Formatters.Multipart.html

Demonstrates formatting a simple key-value pair for multipart submission.

```elixir
iex> FormData.Formatters.Multipart.output([{:key, "one"}], [])
{ :multipart, [{ "", "one", { "form-data", [ {"name", "\"key\""} ] }, [] }] }
```

--------------------------------

### Configure request options

Source: https://hexdocs.pm/httpoison/index.html

Examples of passing SSL and timeout options to requests.

```elixir
token = "some_token_from_another_request"
url = "https://example.com/api/endpoint_that_needs_a_bearer_token"
headers = ["Authorization": "Bearer #{token}", "Accept": "Application/json; Charset=utf-8"]
options = [ssl: [{:versions, [:'tlsv1.2']}], recv_timeout: 500]
{:ok, response} = HTTPoison.get(url, headers, options)
```

```elixir
url = "https://example.org/api/endpoint_that_needs_client_cert"
options = [ssl: [certfile: "certs/client.crt"]]
{:ok, response} = HTTPoison.post(url, [], options)
```

--------------------------------

### Example multipart response body

Source: https://hexdocs.pm/httpoison/HTTPoison.Handlers.Multipart.html

A raw example of a multipart response body structure.

```text
--123
Content-type: application/json
{"1": "first"}
--123
Content-type: application/json
{"2": "second"}
--123--
```

--------------------------------

### Configure SSL and Timeout Options for GET Request

Source: https://hexdocs.pm/httpoison/readme.html

Set custom SSL options, such as TLS version, and a receive timeout for a GET request.

```elixir
token = "some_token_from_another_request"
url = "https://example.com/api/endpoint_that_needs_a_bearer_token"
headers = ["Authorization": "Bearer #{token}", "Accept": "Application/json; Charset=utf-8"]
options = [ssl: [{:versions, [:'tlsv1.2']}], recv_timeout: 500]
{:ok, response} = HTTPoison.get(url, headers, options)
```

--------------------------------

### Wrap HTTPoison.Base for API Clients

Source: https://hexdocs.pm/httpoison/readme.html

Extend HTTPoison.Base to create custom API clients. This example demonstrates building a client for the GitHub API, using Poison for JSON decoding and defining custom request/response processing.

```elixir
defmodule GitHub do
  use HTTPoison.Base

  @expected_fields ~w(
    login id avatar_url gravatar_id url html_url followers_url
    following_url gists_url starred_url subscriptions_url
    organizations_url repos_url events_url received_events_url type
    site_admin name company blog location email hireable bio
    public_repos public_gists followers following created_at updated_at
  )

  def process_request_url(url) do
    "https://api.github.com" <> url
  end

  def process_response_body(body) do
    body
    |> Poison.decode!
    |> Map.take(@expected_fields)
    |> Enum.map(fn({k, v}) -> {String.to_atom(k), v} end)
  end
end
```

```elixir
iex> GitHub.start
iex> GitHub.get!("/users/myfreeweb").body[:public_repos]
37
```

```elixir
def process_request_body(body), do: body

def process_request_headers(headers) when is_map(headers) do
  Enum.into(headers, [])
end

def process_request_headers(headers), do: headers

def process_request_options(options), do: options

def process_request_url(url), do: url

def process_response_body(body), do: body

def process_response_chunk(chunk), do: chunk

def process_response_headers(headers), do: headers

def process_response_status_code(status_code), do: status_code
```

--------------------------------

### HTTP GET Requests

Source: https://hexdocs.pm/httpoison/HTTPoison.Base.html

This section covers the GET method, used for retrieving resources. It includes variations for specifying URL, headers, and options, and handling both successful responses and errors.

```APIDOC
## GET /:url

### Description
Retrieves a resource from the specified URL.

### Method
GET

### Endpoint
/:url

### Parameters
#### Path Parameters
- **url** (url()) - Required - The URL of the resource to retrieve.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "GET /users/123"
}
```

### Response
#### Success Response (200)
- **response** (HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()) - The response from the server.
#### Error Response
- **error** (HTTPoison.Error.t()) - An error object if the request fails.

#### Response Example
```json
{
  "example": "{:ok, %HTTPoison.Response{status_code: 200, body: \"{\"name\": \"John Doe\"}\"}}"
}
```

## GET /:url, headers

### Description
Retrieves a resource from the specified URL with custom headers.

### Method
GET

### Endpoint
/:url

### Parameters
#### Path Parameters
- **url** (url()) - Required - The URL of the resource to retrieve.
- **headers** (headers()) - Required - A list of headers to include in the request.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "GET /users/123, [{"Accept", "application/json"}]"
}
```

### Response
#### Success Response (200)
- **response** (HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()) - The response from the server.
#### Error Response
- **error** (HTTPoison.Error.t()) - An error object if the request fails.

#### Response Example
```json
{
  "example": "{:ok, %HTTPoison.Response{status_code: 200, body: \"{\"name\": \"John Doe\"}\"}}"
}
```

## GET /:url, headers, options

### Description
Retrieves a resource from the specified URL with custom headers and options.

### Method
GET

### Endpoint
/:url

### Parameters
#### Path Parameters
- **url** (url()) - Required - The URL of the resource to retrieve.
- **headers** (headers()) - Required - A list of headers to include in the request.
- **options** (options()) - Required - Additional options for the request.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "GET /users/123, [{"Accept", "application/json"}], [timeout: 5000]"
}
```

### Response
#### Success Response (200)
- **response** (HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()) - The response from the server.
#### Error Response
- **error** (HTTPoison.Error.t()) - An error object if the request fails.

#### Response Example
```json
{
  "example": "{:ok, %HTTPoison.Response{status_code: 200, body: \"{\"name\": \"John Doe\"}\"}}"
}
```

## GET! /:url

### Description
Retrieves a resource from the specified URL and raises an error if the request fails.

### Method
GET

### Endpoint
/:url

### Parameters
#### Path Parameters
- **url** (url()) - Required - The URL of the resource to retrieve.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "GET! /users/123"
}
```

### Response
#### Success Response (200)
- **response** (HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()) - The response from the server.

#### Response Example
```json
{
  "example": "%HTTPoison.Response{status_code: 200, body: \"{\"name\": \"John Doe\"}\"}"
}
```

## GET! /:url, headers

### Description
Retrieves a resource from the specified URL with custom headers and raises an error if the request fails.

### Method
GET

### Endpoint
/:url

### Parameters
#### Path Parameters
- **url** (url()) - Required - The URL of the resource to retrieve.
- **headers** (headers()) - Required - A list of headers to include in the request.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "GET! /users/123, [{"Accept", "application/json"}]"
}
```

### Response
#### Success Response (200)
- **response** (HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()) - The response from the server.

#### Response Example
```json
{
  "example": "%HTTPoison.Response{status_code: 200, body: \"{\"name\": \"John Doe\"}\"}"
}
```

## GET! /:url, headers, options

### Description
Retrieves a resource from the specified URL with custom headers and options, raising an error if the request fails.

### Method
GET

### Endpoint
/:url

### Parameters
#### Path Parameters
- **url** (url()) - Required - The URL of the resource to retrieve.
- **headers** (headers()) - Required - A list of headers to include in the request.
- **options** (options()) - Required - Additional options for the request.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "GET! /users/123, [{"Accept", "application/json"}], [timeout: 5000]"
}
```

### Response
#### Success Response (200)
- **response** (HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()) - The response from the server.

#### Response Example
```json
{
  "example": "%HTTPoison.Response{status_code: 200, body: \"{\"name\": \"John Doe\"}\"}"
}
```
```

--------------------------------

### Add HTTPoison to Mix Dependencies

Source: https://hexdocs.pm/httpoison/readme.html

Add HTTPoison to your project's dependencies in `mix.exs` to install it.

```elixir
def deps do
  [
    {:httpoison, "~> 2.0"}
  ]
end
```

--------------------------------

### GET Request

Source: https://hexdocs.pm/httpoison/HTTPoison.html

Issues a GET request to the specified URL.

```APIDOC
## GET / 

### Description
Issues a GET request to the given url.

### Method
GET

### Parameters
#### Path Parameters
- **url** (binary) - Required - The target URL.

#### Query Parameters
- **headers** (headers) - Optional - Request headers.
- **options** (Keyword.t) - Optional - Request options.

### Response
#### Success Response (200)
- **response** (HTTPoison.Response.t | HTTPoison.AsyncResponse.t) - The successful response object.

#### Error Response
- **error** (HTTPoison.Error.t) - The error reason if the request fails.
```

--------------------------------

### HTTPoison.Base Request Methods

Source: https://hexdocs.pm/httpoison/HTTPoison.Base.html

The HTTPoison.Base module provides standard HTTP methods (GET, POST, PUT, DELETE, etc.) that can be used to issue requests. These methods can be called directly or overridden within a custom module.

```APIDOC
## HTTP Methods

### Description
Standard HTTP request methods provided by the HTTPoison.Base behaviour.

### Methods
- GET(url, headers, options)
- POST(url, body, headers, options)
- PUT(url, body, headers, options)
- PATCH(url, body, headers, options)
- DELETE(url, headers, options)
- HEAD(url, headers, options)
- OPTIONS(url, headers, options)

### Parameters
- **url** (binary) - Required - The target URL for the request.
- **body** (term) - Optional - The request payload.
- **headers** (list) - Optional - Key-value pairs for request headers.
- **options** (keyword) - Optional - Request configuration options.
```

--------------------------------

### HTTPoison Core Functions

Source: https://hexdocs.pm/httpoison/HTTPoison.html

This section details the core functions for making HTTP requests with HTTPoison, including methods for GET, POST, PUT, DELETE, HEAD, and OPTIONS. It also covers both safe versions that return responses and versions that raise exceptions on failure.

```APIDOC
## HTTPoison Request Functions

### Description
Provides functions to issue various HTTP requests.

### Functions

#### DELETE
- `HTTPoison.delete(url, headers \\ [], options \\ [])`: Issues a DELETE request.
- `HTTPoison.delete!(url, headers \\ [], options \\ [])`: Issues a DELETE request, raising an exception on failure.

#### GET
- `HTTPoison.get(url, headers \\ [], options \\ [])`: Issues a GET request.
- `HTTPoison.get!(url, headers \\ [], options \\ [])`: Issues a GET request, raising an exception on failure.

#### HEAD
- `HTTPoison.head(url, headers \\ [], options \\ [])`: Issues a HEAD request.
- `HTTPoison.head!(url, headers \\ [], options \\ [])`: Issues a HEAD request, raising an exception on failure.

#### OPTIONS
- `HTTPoison.options(url, headers \\ [], options \\ [])`: Issues an OPTIONS request.
- `HTTPoison.options!(url, headers \\ [], options \\ [])`: Issues an OPTIONS request, raising an exception on failure.

#### PATCH
- `HTTPoison.patch(url, body, headers \\ [], options \\ [])`: Issues a PATCH request.
- `HTTPoison.patch!(url, body, headers \\ [], options \\ [])`: Issues a PATCH request, raising an exception on failure.

#### POST
- `HTTPoison.post(url, body, headers \\ [], options \\ [])`: Issues a POST request.
- `HTTPoison.post!(url, body, headers \\ [], options \\ [])`: Issues a POST request, raising an exception on failure.

#### PUT
- `HTTPoison.put(url, body \\ "", headers \\ [], options \\ [])`: Issues a PUT request.
- `HTTPoison.put!(url, body \\ "", headers \\ [], options \\ [])`: Issues a PUT request, raising an exception on failure.

### Parameters
- `url` (string): The URL to send the request to.
- `body` (any): The request body (for POST, PUT, PATCH).
- `headers` (list): A list of request headers.
- `options` (list): A list of request options.

### Example Usage
```elixir
# GET request
HTTPoison.get!("https://api.example.com/data")

# POST request with body and headers
HTTPoison.post!("https://api.example.com/users", %{name: "John Doe"}, [{"X-Api-Key", "your_key"}])
```
```

--------------------------------

### Format key-value tuples for URL Encoded requests

Source: https://hexdocs.pm/httpoison_form_data/FormData.Formatters.URLEncoded.html

Use this function to format a stream of key-value tuples for URL-encoded requests. The `:get` option formats for HTTPoison.get, while the default formats for HTTPoison.post. The `:url` option outputs a URL string.

```elixir
iex> FormData.Formatters.URLEncoded.output([{"Name", "Value"}, {"Name2", "Value2"}], [])
{:form, [{"Name", "Value"}, {"Name2", "Value2"}]}
```

```elixir
iex> FormData.Formatters.URLEncoded.output([{"Name", "Value"}, {"Name2", "Value2"}], get: true)
[params: [{"Name", "Value"}, {"Name2", "Value2"}]]
```

```elixir
iex> FormData.Formatters.URLEncoded.output([{"Name", "Value"}, {"Name2", "Value2"}], url: true)
"?Name=Value&Name2=Value2"
```

--------------------------------

### Create FormData.File Struct

Source: https://hexdocs.pm/httpoison_form_data/FormData.File.html

Creates a new FormData.File struct. Requires a string representing the file path.

```elixir
new(path :: String.t()) :: FormData.File.t()
```

--------------------------------

### Create an API client with HTTPoison.Base

Source: https://hexdocs.pm/httpoison/HTTPoison.Base.html

Use the Base module to define a custom client with a base endpoint.

```elixir
defmodule GitHub do
  use HTTPoison.Base

  @endpoint "https://api.github.com"

  def process_request_url(url) do
    @endpoint <> url
  end
end
```

--------------------------------

### Enable request logging

Source: https://hexdocs.pm/httpoison/readme.html

Configure runtime tools and enable hackney tracing for low-level request logging.

```elixir
# Add :runtime_tools to :extra_applications in mix.exs
def application do
  [extra_applications: [:logger, :runtime_tools]]
end
```

```elixir
iex(1)> :hackney_trace.enable(:max, :io)
```

--------------------------------

### HTTPoison.Error Message Function

Source: https://hexdocs.pm/httpoison/HTTPoison.Error.html

Callback implementation for `Exception.message/1` to get a string representation of the error.

```APIDOC
## Function

`message(error)`

### Description

Callback implementation for `Exception.message/1`.

### Parameters

- **error** (`%HTTPoison.Error{}`)

### Returns

- `String.t()` - A string representation of the error.
```

--------------------------------

### create/3

Source: https://hexdocs.pm/httpoison_form_data/FormData.html

Transforms input data into a formatted payload using a specified formatter.

```APIDOC
## create(obj, formatter, output_opts)

### Description
This function chooses the correct formatter and uses it in conjunction with the recursive name-formatting algorithm to produce the desired data structure.

### Parameters
- **obj** (input_type) - Required - The input data (keyword, map, or struct).
- **formatter** (module) - Required - The module defining the formatting behavior (e.g., Multipart or URLEncoded).
- **output_opts** (keyword) - Optional - Configuration options for the output.

### Response
- **Success** ({:ok, payload()}) - Returns the formatted payload.
- **Error** ({:error, String.t()}) - Returns an error message if formatting fails.
```

--------------------------------

### License information

Source: https://hexdocs.pm/httpoison/readme.html

MIT License details for the project.

```text
Copyright © 2013-present Eduardo Gurgel <eduardo@gurgel.me>

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.
```

--------------------------------

### Decoding a multipart response body

Source: https://hexdocs.pm/httpoison/HTTPoison.Handlers.Multipart.html

Usage example for parsing a multipart response body using the decode_body function.

```elixir
HTTPoison.Handlers.Multipart.decode_body(response)
#=> will decode a multipart body, e.g. yielding
# [
#   {[{"Content-Type", "application/json"}], "{"1": "first"}"},
#   {[{"Content-Type", "application/json"}], "{"2": "second"}"}
# ]
```

--------------------------------

### Define output function

Source: https://hexdocs.pm/httpoison_form_data/FormData.Formatters.Multipart.html

Wraps data into a multipart structure for HTTPoison.

```elixir
output(stream :: Enum.t(), _opts :: any()) :: FormData.Formatters.Multipart.t()
```

--------------------------------

### FormData.Formatters.URLEncoded.output/2

Source: https://hexdocs.pm/httpoison_form_data/FormData.Formatters.URLEncoded.html

Formats a stream of key-value tuples for URL Encoded requests. Supports options for GET requests and URL string generation.

```APIDOC
## FormData.Formatters.URLEncoded.output/2

### Description
Format a `stream` of key-value tuples for URL Encoded requests.

### Method
N/A (Function)

### Endpoint
N/A (Function)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```elixir
FormData.Formatters.URLEncoded.output([{"Name", "Value"}, {"Name2", "Value2"}], [])
```

### Response
#### Success Response (200)
- **output** (FormData.Formatters.URLEncoded.t()) - The formatted data.

#### Response Example
```json
{:form, [{"Name", "Value"}, {"Name2", "Value2"}]}
```

### Options
- `:get` (boolean): If true, formats data for `HTTPoison.get`.
- `:url` (boolean): If true, outputs a URL string.

### Examples
```elixir
iex> FormData.Formatters.URLEncoded.output([{"Name", "Value"}, {"Name2", "Value2"}], [])
{:form, [{"Name", "Value"}, {"Name2", "Value2"}]}

iex> FormData.Formatters.URLEncoded.output([{"Name", "Value"}, {"Name2", "Value2"}], get: true)
[params: [{"Name", "Value"}, {"Name2", "Value2"}]]

iex> FormData.Formatters.URLEncoded.output([{"Name", "Value"}, {"Name2", "Value2"}], url: true)
"?Name=Value&Name2=Value2"
```
```

--------------------------------

### Wrap HTTPoison.Base for API Clients

Source: https://hexdocs.pm/httpoison/index.html

Create a custom API client by using HTTPoison.Base and overriding processing functions.

```elixir
defmodule GitHub do
  use HTTPoison.Base

  @expected_fields ~w(
    login id avatar_url gravatar_id url html_url followers_url
    following_url gists_url starred_url subscriptions_url
    organizations_url repos_url events_url received_events_url type
    site_admin name company blog location email hireable bio
    public_repos public_gists followers following created_at updated_at
  )

  def process_request_url(url) do
    "https://api.github.com" <> url
  end

  def process_response_body(body) do
    body
    |> Poison.decode!
    |> Map.take(@expected_fields)
    |> Enum.map(fn({k, v}) -> {String.to_atom(k), v} end)
  end
end
```

```elixir
iex> GitHub.start
iex> GitHub.get!("/users/myfreeweb").body[:public_repos]
37
```

--------------------------------

### Define entry_type

Source: https://hexdocs.pm/httpoison_form_data/FormData.Formatters.Multipart.html

Specifies whether the entry is a string or a file.

```elixir
entry_type() :: String.t() | :file
```

--------------------------------

### Make an HTTP POST Request

Source: https://hexdocs.pm/httpoison/HTTPoison.html

Use this to make an HTTP request with explicit method, URL, body, and headers. This method returns a tuple indicating success or error.

```elixir
request(:post, "https://my.website.com", "{\"foo\": 3}", [{"Accept", "application/json"}])
```

--------------------------------

### Make an HTTP Request with Exception Handling

Source: https://hexdocs.pm/httpoison/HTTPoison.html

This function is similar to `request/5` but raises an exception if the request fails, returning only the successful response.

```elixir
request!(method, url, body \" \"", headers \" []", options \" [])
```

--------------------------------

### Make an HTTP POST Request with a Request Struct

Source: https://hexdocs.pm/httpoison/HTTPoison.html

Use this to make an HTTP request when you have the request details pre-defined in an HTTPoison.Request struct. This method raises an exception on failure.

```elixir
request = %HTTPoison.Request{
  method: :post,
  url: "https://my.website.com",
  body: "{\"foo\": 3}",
  headers: [{"Accept", "application/json"}]
}

request(request)
```

--------------------------------

### Configure SSL Client Certificate for POST Request

Source: https://hexdocs.pm/httpoison/readme.html

Specify SSL options, including a client certificate file, for a POST request.

```elixir
url = "https://example.org/api/endpoint_that_needs_client_cert"
options = [ssl: [certfile: "certs/client.crt"]]
{:ok, response} = HTTPoison.post(url, [], options)
```

--------------------------------

### create!/3

Source: https://hexdocs.pm/httpoison_form_data/FormData.html

Transforms input data into a formatted payload, raising an error on failure.

```APIDOC
## create!(obj, formatter, output_opts)

### Description
This function chooses the correct formatter and uses it in conjunction with the recursive name-formatting algorithm to produce the desired data structure, raising an exception if the operation fails.

### Parameters
- **obj** (input_type) - Required - The input data (keyword, map, or struct).
- **formatter** (module) - Required - The module defining the formatting behavior.
- **output_opts** (keyword) - Optional - Configuration options for the output.

### Response
- **Success** (payload()) - Returns the formatted payload.
```

--------------------------------

### HTTP OPTIONS Requests

Source: https://hexdocs.pm/httpoison/HTTPoison.Base.html

This section covers the OPTIONS method, used for describing the communication options for the target resource. It includes variations for specifying URL, headers, and options, and handling both successful responses and errors.

```APIDOC
## OPTIONS /:url

### Description
Describes the communication options for the target resource at the specified URL.

### Method
OPTIONS

### Endpoint
/:url

### Parameters
#### Path Parameters
- **url** (url()) - Required - The URL of the resource.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "OPTIONS /users/123"
}
```

### Response
#### Success Response (200)
- **response** (HTTPoison.Response.t() | HTTPoison.AsyncResponse.t() | HTTPoison.MaybeRedirect.t()) - The response from the server containing communication options.
#### Error Response
- **error** (HTTPoison.Error.t()) - An error object if the request fails.

#### Response Example
```json
{
  "example": "{:ok, %HTTPoison.Response{status_code: 200, body: \"Allow: GET, POST\"}}"
}
```

## OPTIONS /:url, headers

### Description
Describes the communication options for the target resource at the specified URL with custom headers.

### Method
OPTIONS

### Endpoint
/:url

### Parameters
#### Path Parameters
- **url** (url()) - Required - The URL of the resource.
- **headers** (headers()) - Required - A list of headers to include in the request.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "OPTIONS /users/123, [{"Accept", "application/json"}]"
}
```

### Response
#### Success Response (200)
- **response** (HTTPoison.Response.t() | HTTPoison.AsyncResponse.t() | HTTPoison.MaybeRedirect.t()) - The response from the server containing communication options.
#### Error Response
- **error** (HTTPoison.Error.t()) - An error object if the request fails.

#### Response Example
```json
{
  "example": "{:ok, %HTTPoison.Response{status_code: 200, body: \"Allow: GET, POST\"}}"
}
```

## OPTIONS /:url, headers, options

### Description
Describes the communication options for the target resource at the specified URL with custom headers and options.

### Method
OPTIONS

### Endpoint
/:url

### Parameters
#### Path Parameters
- **url** (url()) - Required - The URL of the resource.
- **headers** (headers()) - Required - A list of headers to include in the request.
- **options** (options()) - Required - Additional options for the request.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "OPTIONS /users/123, [{"Accept", "application/json"}], [timeout: 5000]"
}
```

### Response
#### Success Response (200)
- **response** (HTTPoison.Response.t() | HTTPoison.AsyncResponse.t() | HTTPoison.MaybeRedirect.t()) - The response from the server containing communication options.
#### Error Response
- **error** (HTTPoison.Error.t()) - An error object if the request fails.

#### Response Example
```json
{
  "example": "{:ok, %HTTPoison.Response{status_code: 200, body: \"Allow: GET, POST\"}}"
}
```

## OPTIONS! /:url

### Description
Describes the communication options for the target resource at the specified URL and raises an error if the request fails.

### Method
OPTIONS

### Endpoint
/:url

### Parameters
#### Path Parameters
- **url** (url()) - Required - The URL of the resource.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "OPTIONS! /users/123"
}
```

### Response
#### Success Response (200)
- **response** (HTTPoison.Response.t() | HTTPoison.AsyncResponse.t() | HTTPoison.MaybeRedirect.t()) - The response from the server containing communication options.

#### Response Example
```json
{
  "example": "%HTTPoison.Response{status_code: 200, body: \"Allow: GET, POST\"}"
}
```

## OPTIONS! /:url, headers

### Description
Describes the communication options for the target resource at the specified URL with custom headers and raises an error if the request fails.

### Method
OPTIONS

### Endpoint
/:url

### Parameters
#### Path Parameters
- **url** (url()) - Required - The URL of the resource.
- **headers** (headers()) - Required - A list of headers to include in the request.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "OPTIONS! /users/123, [{"Accept", "application/json"}]"
}
```

### Response
#### Success Response (200)
- **response** (HTTPoison.Response.t() | HTTPoison.AsyncResponse.t() | HTTPoison.MaybeRedirect.t()) - The response from the server containing communication options.

#### Response Example
```json
{
  "example": "%HTTPoison.Response{status_code: 200, body: \"Allow: GET, POST\"}"
}
```

## OPTIONS! /:url, headers, options

### Description
Describes the communication options for the target resource at the specified URL with custom headers and options, raising an error if the request fails.

### Method
OPTIONS

### Endpoint
/:url

### Parameters
#### Path Parameters
- **url** (url()) - Required - The URL of the resource.
- **headers** (headers()) - Required - A list of headers to include in the request.
- **options** (options()) - Required - Additional options for the request.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "OPTIONS! /users/123, [{"Accept", "application/json"}], [timeout: 5000]"
}
```

### Response
#### Success Response (200)
- **response** (HTTPoison.Response.t() | HTTPoison.AsyncResponse.t() | HTTPoison.MaybeRedirect.t()) - The response from the server containing communication options.

#### Response Example
```json
{
  "example": "%HTTPoison.Response{status_code: 200, body: \"Allow: GET, POST\"}"
}
```
```

--------------------------------

### Execute requests using a custom client

Source: https://hexdocs.pm/httpoison/HTTPoison.Base.html

Perform requests through the custom module to apply defined processing logic.

```elixir
GitHub.get("/users/octocat/orgs")
#=> will issue a GET request at https://api.github.com/users/octocat/orgs
```

--------------------------------

### Implement output callback

Source: https://hexdocs.pm/httpoison_form_data/FormData.Formatters.html

Implement this callback to process the stream output from FormData.to_form's recursion. It takes the stream data and a keyword list of options to produce the desired end-result, such as a string.

```Elixir
output(data :: Enumerable.t(), options :: keyword(boolean())) :: any()
```

--------------------------------

### HTTPoison.Response Struct

Source: https://hexdocs.pm/httpoison/HTTPoison.Response.html

Defines the fields contained within the HTTPoison.Response struct.

```APIDOC
## HTTPoison.Response

### Description
The HTTPoison.Response struct represents the response received from an HTTP request.

### Fields
- **body** (term) - The response body.
- **headers** (list) - The response headers.
- **request** (HTTPoison.Request.t) - The original request struct.
- **request_url** (HTTPoison.Request.url) - The URL of the request.
- **status_code** (integer) - The HTTP status code of the response.
```

--------------------------------

### FormData.File Module

Source: https://hexdocs.pm/httpoison_form_data/index.html

This module is part of the httpoison_form_data library.

```APIDOC
## Module: FormData.File

### Description
This module is part of the httpoison_form_data library. Specific functionalities are not detailed in the provided text.
```

--------------------------------

### request!/5

Source: https://hexdocs.pm/httpoison/HTTPoison.html

Issues an HTTP request with the given method to the given url, raising an exception in case of failure. `request!/5` works exactly like `request/5` but it returns just the response in case of a successful request, raising an exception in case the request fails.

```APIDOC
## request!/5

### Description
Issues an HTTP request with the given method to the given url, raising an exception in case of failure.
`request!/5` works exactly like `request/5` but it returns just the response in case of a successful request, raising an exception in case the request fails.

### Method
POST

### Endpoint
N/A (Uses method, url, body, headers, options)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **method** (atom) - Required - HTTP method as an atom (`:get`, `:head`, `:post`, `:put`, `:delete`, etc.)
- **url** (binary() | char_list()) - Required - target url as a binary string or char list
- **body** (any()) - Optional - request body. Defaults to "".
- **headers** (Keyword.t()) - Optional - HTTP headers as an orddict (e.g., `[{"Accept", "application/json"}]`). Defaults to `[]`.
- **options** (Keyword.t()) - Optional - Keyword list of options. Defaults to `[]`.

### Request Example
```elixir
request!(:post, "https://my.website.com", "{\"foo\": 3}", [{"Accept", "application/json"}])
```

### Response
#### Success Response (200)
- **response** (HTTPoison.Response.t() | HTTPoison.AsyncResponse.t() | HTTPoison.MaybeRedirect.t()) - The successful response object.

#### Response Example
```elixir
%HTTPoison.Response{body: "some body", status_code: 200}
```

### Error Handling
Raises an exception in case of failure.

### Error Example
```elixir
# Raises an exception, does not return an error tuple.
request!(:get, "invalid-url")
```
```

--------------------------------

### next_attempt/2

Source: https://hexdocs.pm/httpoison_retry/index.html

Calculates the parameters for the next retry attempt.

```APIDOC
## next_attempt(attempt, opts)

### Description
Calculates the next attempt logic based on the current attempt and provided options.

### Parameters
- **attempt** (any) - Required - The current attempt state.
- **opts** (keyword list) - Required - Configuration options.
```

--------------------------------

### Define filename

Source: https://hexdocs.pm/httpoison_form_data/FormData.Formatters.Multipart.html

Type alias for a filename string.

```elixir
filename() :: String.t()
```

--------------------------------

### Define filename_key

Source: https://hexdocs.pm/httpoison_form_data/FormData.Formatters.Multipart.html

Type alias for a filename key string.

```elixir
filename_key() :: String.t()
```

--------------------------------

### Handle Async HTTP Requests

Source: https://hexdocs.pm/httpoison/readme.html

Initiate asynchronous HTTP requests and process the response in chunks. Use `stream_to: self` to send response messages to the current process. Be cautious of message flooding with large responses; consider `async: :once` for single-chunk processing.

```elixir
iex> HTTPoison.get! "https://github.com/", %{}, stream_to: self
%HTTPoison.AsyncResponse{id: #Reference<0.0.0.1654>}
iex> flush
%HTTPoison.AsyncStatus{code: 200, id: #Reference<0.0.0.1654>}
%HTTPoison.AsyncHeaders{headers: %{"Connection" => "keep-alive", ...}, id: #Reference<0.0.0.1654>}
%HTTPoison.AsyncChunk{chunk: "<!DOCTYPE html>...", id: #Reference<0.0.0.1654>}
%HTTPoison.AsyncEnd{id: #Reference<0.0.0.1654>}
:ok
```

--------------------------------

### Define key_metadata

Source: https://hexdocs.pm/httpoison_form_data/FormData.Formatters.Multipart.html

Metadata structure for key-based multipart entries.

```elixir
key_metadata() :: {name_key(), name()}
```

--------------------------------

### FormData.File.new/1

Source: https://hexdocs.pm/httpoison_form_data/FormData.File.html

Creates a new FormData.File struct with the specified file path.

```APIDOC
## Function new(path)

### Description
Creates a new File struct containing the path specified. This function is an addition based on suprafly’s fork for northofsummer.

### Method
`FormData.File.new/1`

### Parameters
#### Path Parameters
- **path** (String.t()) - Required - The file path to be included in the FormData.

### Response
#### Success Response (FormData.File.t())
- **%FormData.File{path: String.t()}** - A new FormData.File struct.

### Request Example
```elixir
FormData.File.new("/path/to/your/file.txt")
```

### Response Example
```elixir
%FormData.File{path: "/path/to/your/file.txt"}
```
```

--------------------------------

### Make a POST Request with HTTPoison

Source: https://hexdocs.pm/httpoison/readme.html

Perform a POST request with a JSON body and custom headers. Returns an OK tuple with the response or an error tuple.

```elixir
iex> HTTPoison.post "https://postman-echo.com/post", "{\"body\": \"test\"}", [{"Content-Type", "application/json"}]
{:ok,
 %HTTPoison.Response{
   status_code: 200,
   body: "{\n  \"args\": {},\n  \"data\": {\n    \"body\": \"test\"\n  },\n  \"files\": {},\n  \"form\": {},\n  \"headers\": {\n    \"x-forwarded-proto\": \"https\",\n    \"x-forwarded-port\": \"443\",\n    \"host\": \"postman-echo.com\",\n    \"x-amzn-trace-id\": \"Root=1-6446255e-703101813ec2e395202ab494\",\n    \"content-length\": \"16\",\n    \"user-agent\": \"hackney/1.18.1\",\n    \"content-type\": \"application/json\"\n  },\n  \"json\": {\n    \"body\": \"test\"\n  },\n  \"url\": \"https://postman-echo.com/post\"\n}",
   headers: [ ... ]
 }}
```

--------------------------------

### Define FormData.File Type

Source: https://hexdocs.pm/httpoison_form_data/FormData.File.html

Defines the structure of a FormData.File, which includes a path.

```elixir
t() :: %FormData.File{path: String.t()}
```

--------------------------------

### PUT / Request Methods

Source: https://hexdocs.pm/httpoison/HTTPoison.Base.html

Methods for performing PUT requests.

```APIDOC
## PUT / 

### Description
Performs a PUT request to the specified URL with optional body and headers.

### Method
PUT

### Parameters
#### Path Parameters
- **url** (url()) - Required - The target URL.

#### Request Body
- **body** (body()) - Optional - The request payload.
- **headers** (headers()) - Optional - Request headers.

### Response
#### Success Response (200)
- **result** (HTTPoison.Response.t | HTTPoison.AsyncResponse.t | HTTPoison.MaybeRedirect.t) - The response object.

#### Error Response
- **error** (HTTPoison.Error.t) - Returned by non-bang (!) methods on failure.
```

--------------------------------

### POST Request

Source: https://hexdocs.pm/httpoison/HTTPoison.html

Issues a POST request to the given URL, raising an exception in case of failure. If the request does not fail, the response is returned.

```APIDOC
## POST /api/resource

### Description
Issues a POST request to the given URL.

### Method
POST

### Endpoint
/api/resource

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **body** (any) - Required - The request body.
- **headers** (list()) - Optional - A list of headers.
- **options** (Keyword.t()) - Optional - Request options.

### Request Example
```elixir
HTTPoison.post!("http://example.com", "some data", [{"Content-Type", "text/plain"}])
```

### Response
#### Success Response (200)
- **response** (HTTPoison.Response.t() | HTTPoison.AsyncResponse.t() | HTTPoison.MaybeRedirect.t()) - The HTTP response object.

#### Response Example
```elixir
{:ok, %HTTPoison.Response{body: "...", status_code: 200}}
```
```

--------------------------------

### PUT Request (with exception)

Source: https://hexdocs.pm/httpoison/HTTPoison.html

Issues a PUT request to the given URL, raising an exception in case of failure. If the request does not fail, the response is returned.

```APIDOC
## PUT /api/resource/{id}!

### Description
Issues a PUT request to the given URL, raising an exception in case of failure.

### Method
PUT

### Endpoint
/api/resource/{id}

### Parameters
#### Path Parameters
- **id** (binary) - Required - The ID of the resource to update.

#### Query Parameters
None

#### Request Body
- **body** (any) - Optional - The request body. Defaults to "".
- **headers** (list()) - Optional - A list of headers. Defaults to `[]`.
- **options** (Keyword.t()) - Optional - Request options. Defaults to `[]`.

### Request Example
```elixir
HTTPoison.put!("http://example.com/resource/123", %{name: "updated name"})
```

### Response
#### Success Response (200)
- **response** (HTTPoison.Response.t() | HTTPoison.AsyncResponse.t() | HTTPoison.MaybeRedirect.t()) - The HTTP response object.

#### Response Example
```elixir
%HTTPoison.Response{body: "Updated successfully", status_code: 200}
```
```

--------------------------------

### to_curl/1

Source: https://hexdocs.pm/httpoison/HTTPoison.Request.html

Converts an HTTPoison.Request struct into an equivalent curl command string.

```APIDOC
## to_curl(request)

### Description
Returns an equivalent `curl` command for the given request struct.

### Parameters
- **request** (t()) - The HTTPoison.Request struct to convert.

### Response
- **Success** ({:ok, binary()}) - The generated curl command string.
- **Error** ({:error, atom()}) - Error reason if conversion fails.

### Request Example
request = %HTTPoison.Request{url: "https://api.github.com", method: :get, headers: [{"Content-Type", "application/json"}]}
```
Tokens:
Raw