Integrating with External APIs in Elixir

What You’ll Learn 📚

• Understanding APIs and their importance
• Key terminology related to APIs
• How to make HTTP requests in Elixir
• Handling JSON responses
• Common pitfalls and troubleshooting tips

Introduction to APIs

APIs, or Application Programming Interfaces, are like bridges that allow different software applications to communicate with each other. Imagine APIs as waiters in a restaurant who take your order (request) and bring you your food (response). In programming, APIs let your application request data or services from another application.

Key Terminology

• Endpoint: A specific URL where an API can be accessed.
• Request: The act of asking for data or action from an API.
• Response: The data or action returned by an API.
• HTTP Methods: Actions you can perform with APIs, like GET (retrieve data) or POST (send data).
• JSON: A common data format used in API responses.

Getting Started with Elixir and HTTP Requests

Let’s start with the simplest example: making a GET request to an API using Elixir. We’ll use the HTTPoison library, a popular choice for HTTP requests in Elixir.

Setup Instructions

First, ensure you have Elixir installed. Then, create a new Elixir project:

mix new api_example

Next, add HTTPoison to your project by editing the mix.exs file:

defp deps do
  [
    {:httpoison, "~> 1.8"}
  ]
end

Run the following command to fetch the dependencies:

mix deps.get

Simple GET Request Example

defmodule ApiExample do
  def fetch_data do
    case HTTPoison.get("https://jsonplaceholder.typicode.com/posts/1") do
      {:ok, %HTTPoison.Response{status_code: 200, body: body}} ->
        IO.puts("Success! Here's the data:")
        IO.puts(body)
      {:ok, %HTTPoison.Response{status_code: status_code}} ->
        IO.puts("Received unexpected status code: #{status_code}")
      {:error, %HTTPoison.Error{reason: reason}} ->
        IO.puts("Failed to fetch data: #{reason}")
    end
  end
end

ApiExample.fetch_data()

Success! Here's the data:
{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
}

Handling JSON Responses

APIs often return data in JSON format. To work with JSON in Elixir, we can use the Jason library. Let’s modify our example to parse the JSON response:

defmodule ApiExample do
  def fetch_data do
    case HTTPoison.get("https://jsonplaceholder.typicode.com/posts/1") do
      {:ok, %HTTPoison.Response{status_code: 200, body: body}} ->
        case Jason.decode(body) do
          {:ok, data} ->
            IO.inspect(data, label: "Parsed JSON")
          {:error, _} ->
            IO.puts("Failed to parse JSON")
        end
      {:ok, %HTTPoison.Response{status_code: status_code}} ->
        IO.puts("Received unexpected status code: #{status_code}")
      {:error, %HTTPoison.Error{reason: reason}} ->
        IO.puts("Failed to fetch data: #{reason}")
    end
  end
end

ApiExample.fetch_data()

Parsed JSON: %{
  "body" => "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto",
  "id" => 1,
  "title" => "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "userId" => 1
}

Progressively Complex Examples

Example 1: Making a POST Request

Let’s try sending data to an API using a POST request. We’ll send a new post to the same API:

defmodule ApiExample do
  def create_post do
    url = "https://jsonplaceholder.typicode.com/posts"
    headers = [{"Content-Type", "application/json"}]
    body = Jason.encode!(%{title: "foo", body: "bar", userId: 1})

    case HTTPoison.post(url, body, headers) do
      {:ok, %HTTPoison.Response{status_code: 201, body: body}} ->
        IO.puts("Post created successfully!")
        IO.puts(body)
      {:ok, %HTTPoison.Response{status_code: status_code}} ->
        IO.puts("Received unexpected status code: #{status_code}")
      {:error, %HTTPoison.Error{reason: reason}} ->
        IO.puts("Failed to create post: #{reason}")
    end
  end
end

ApiExample.create_post()

Post created successfully!
{
  "id": 101,
  "title": "foo",
  "body": "bar",
  "userId": 1
}

Example 2: Handling API Rate Limits

Some APIs have rate limits, meaning you can only make a certain number of requests in a given time frame. Let’s simulate handling rate limits:

defmodule ApiExample do
  def fetch_with_rate_limit do
    url = "https://jsonplaceholder.typicode.com/posts/1"

    for _ <- 1..5 do
      case HTTPoison.get(url) do
        {:ok, %HTTPoison.Response{status_code: 200, body: body}} ->
          IO.puts("Fetched data successfully")
        {:ok, %HTTPoison.Response{status_code: 429}} ->
          IO.puts("Rate limit exceeded, retrying...")
          :timer.sleep(1000)
          fetch_with_rate_limit()
        {:error, %HTTPoison.Error{reason: reason}} ->
          IO.puts("Failed to fetch data: #{reason}")
      end
    end
  end
end

ApiExample.fetch_with_rate_limit()

Fetched data successfully
Rate limit exceeded, retrying...
Fetched data successfully

Example 3: Authenticating API Requests

Many APIs require authentication. Here’s how you can include an API key in your request headers:

defmodule ApiExample do
  def fetch_with_auth do
    url = "https://api.example.com/secure-data"
    headers = [
      {"Authorization", "Bearer YOUR_API_KEY"},
      {"Content-Type", "application/json"}
    ]

    case HTTPoison.get(url, headers) do
      {:ok, %HTTPoison.Response{status_code: 200, body: body}} ->
        IO.puts("Authenticated request successful!")
        IO.puts(body)
      {:ok, %HTTPoison.Response{status_code: status_code}} ->
        IO.puts("Received unexpected status code: #{status_code}")
      {:error, %HTTPoison.Error{reason: reason}} ->
        IO.puts("Failed to fetch data: #{reason}")
    end
  end
end

ApiExample.fetch_with_auth()

Authenticated request successful!
{
  "secure": "data"
}

Common Questions and Answers

1. What is an API?

   An API is a set of rules that allows different software entities to communicate with each other.

2. Why use HTTPoison in Elixir?

   HTTPoison is a widely-used library in Elixir for making HTTP requests, offering a simple and flexible API.

3. What is JSON?

   JSON (JavaScript Object Notation) is a lightweight data-interchange format that’s easy for humans to read and write, and easy for machines to parse and generate.

4. How do I handle errors in API requests?

   Use pattern matching to handle different types of responses and errors, as shown in the examples.

5. What if the API requires an API key?

   Include the API key in your request headers, typically using the Authorization header.

6. How do I parse JSON in Elixir?

   Use the Jason library to decode JSON strings into Elixir maps.

7. What is a rate limit?

   A rate limit is a restriction on the number of requests you can make to an API in a given time period.

8. How can I retry a request after hitting a rate limit?

   Implement a retry mechanism with a delay, as shown in the rate limit example.

9. Why is my request failing with a 404 error?

   A 404 error means the requested resource was not found. Check the URL and endpoint.

10. What does a 500 status code mean?

    A 500 status code indicates a server error. The issue is on the server side, not with your request.

11. How do I send data in a POST request?

    Encode your data as a JSON string and include it in the request body.

12. What is an endpoint?

    An endpoint is a specific URL where an API can be accessed.

13. How do I include headers in my request?

    Pass a list of headers as the third argument to HTTPoison.get or HTTPoison.post.

14. What if the API returns XML instead of JSON?

    Use an XML parsing library to handle XML responses.

15. Can I use other HTTP methods besides GET and POST?

    Yes, HTTPoison supports other methods like PUT, DELETE, etc.

16. How do I handle timeouts?

    Configure timeout settings in HTTPoison options.

17. What is a bearer token?

    A bearer token is a type of access token used in authentication headers.

18. How do I debug API requests?

    Use IO.inspect to print request and response details for debugging.

19. What if my API request returns a 403 error?

    A 403 error means access is forbidden. Check your authentication credentials.

20. How do I test API requests in Elixir?

    Use ExUnit for testing and mock HTTP requests with libraries like Mox.

Troubleshooting Common Issues

If you encounter a 404 error, double-check the endpoint URL. A 404 means the resource wasn’t found.

If you hit a rate limit, implement a retry mechanism with a delay to avoid overwhelming the server.

For authentication issues, ensure your API key is correct and included in the request headers.

Practice Exercises

• Modify the POST request example to include additional fields in the JSON body.
• Implement a retry mechanism for handling 500 server errors.
• Create a function that fetches data from multiple endpoints and combines the results.

For more information, check out the HTTPoison documentation and the Jason documentation.

Keep practicing, and soon you’ll be an API integration pro! 🌟