Welcome to the first lesson of this course on API Authentication Methods with Requests-Scala. In this lesson, we will explore how to access protected routes using API keys. Understanding API authentication is crucial because it ensures that only authorized users can interact with specific parts of an API.

Among various methods, API keys are a prevalent way to authenticate requests. They serve as a simple passkey to gain access to protected routes. By the end of this lesson, you will know how to integrate API keys into your requests to securely access API endpoints.

Authentication is a process that verifies the identity of a client attempting to access a resource. In RESTful APIs, authentication ensures that requests made to an endpoint are permitted and secure. The purpose of authentication in RESTful APIs is to protect data and resources from unauthorized access. By verifying the client's identity, the API can ensure that only authorized users can perform certain actions or access specific data.

Common methods of authentication in RESTful APIs include:

• API Keys: A unique token generated for each client to grant access to the API. It acts like a secret passcode.
• Sessions: Involves storing authentication details on the server side, typically using a session ID to maintain state between requests.
• JWT (JSON Web Tokens): Compact tokens that verify the identity of the client and carry additional claims.
• Other Methods: Authentication methods like OAuth, which provides secure delegated access, and Basic Authentication, using encoded usernames and passwords, are also prevalent but will not be covered in this course.

Each of these methods varies in complexity and security levels, offering different benefits depending on the use case. In this lesson, we will focus specifically on integrating API keys into your requests.

Before diving into the specifics of API keys, let's take a moment to understand HTTP headers. HTTP headers function like envelopes, carrying additional information about the request or response. They can include various kinds of data, such as:

• Content Type: Specifies the media type of the resource, e.g., application/json.
• User Agent: Provides information about the client software, useful for analytics.
• Authentication Details: Credentials like API keys to access protected resources.

Headers can serve different purposes, such as specifying the preferred language (Accept-Language) or content type. Using the Requests-Scala library, you can easily add headers to a request by including them in a map and passing this map to the headers parameter of the request function:

Scala
Copy to clipboard
1import requests.*
2
3val response = requests.get("http://example.com", headers = Map("Content-Type" -> "application/json"))

In this example, the Content-Type header is added to the request to specify that the client expects JSON data. Simply pass a map of key-value pairs to the headers parameter to include any required headers in your request.

API keys are typically provided by the service you wish to access. After registering for an account, you might receive this key via email, or it could be available in your account settings on the provider's website. Once obtained, you can assign the API key as a straightforward variable in your code for easy use when making requests:

Scala
Copy to clipboard
1val apiKey = "123e4567-e89b-12d3-a456-426614174000"

This key acts as your credential to access protected API routes. However, directly placing API keys in your code is not the most secure practice, especially for sharing or deploying applications.

To enhance security and manage API keys more effectively, we can use environment variables loaded from a .env file using the dotenv-java library. Here's how to set this up:

1. First, create a .env file in your project root:

   Plain text
   Copy to clipboard
   1API_KEY=123e4567-e89b-12d3-a456-426614174000

2. Add the dotenv-java dependency to your project:

   Scala
   Copy to clipboard
   1libraryDependencies += "io.github.cdimascio" % "dotenv-java" % "2.2.0"

3. Load and access the environment variables in your script:

   Scala
   Copy to clipboard
   1import io.github.cdimascio.dotenv.Dotenv
   2
   3// Load environment variables from .env file
   4val dotenv = Dotenv.load()
   5
   6// Retrieve the API key
   7val apiKey = dotenv.get("API_KEY")

This approach not only keeps your API keys secure but also simplifies management across different environments, such as development and production.

Imagine that now our API endpoints, such as /todos, are protected and require a valid API key to access. Without the key, any request will return a 401 Unauthorized error. This is where HTTP headers come into play. We can include the API key in the request headers to authenticate successfully:

Scala
Copy to clipboard
1// Send a request with the API key in headers
2val response = requests.get(s"$baseUrl/todos", headers = Map("X-API-Key" -> apiKey))

In this example, the API key is included in the headers using the X-API-Key custom header. The X-API-Key header is commonly used by APIs to specifically indicate the inclusion of the API key, allowing the server to verify the request as authorized.

Although some APIs might use different header names like Authorization, X-API-Key is widely recognized for clearly distinguishing the key from other types of authentication or authorization tokens. By placing the API key within the headers, the server can verify your request as authorized.

Here's the full implementation, including loading the API key securely from an environment file and handling potential errors during the request:

Scala
Copy to clipboard
1import requests.*
2import scala.util.{Try, Success, Failure}
3import io.github.cdimascio.dotenv.Dotenv
4
5@main def solution(): Unit = 
6  // Base URL for the API
7  val baseUrl = "http://localhost:8000"
8
9  // Load environment variables from a .env file into the script
10  val dotenv = Dotenv.load()
11
12  // Retrieve the API key from the environment variables
13  val apiKey = dotenv.get("API_KEY")
14
15  // Attempt the request and handle the response
16  val result = for
17    response <- Try(get(s"$baseUrl/todos", headers = Map("X-API-Key" -> apiKey)))
18  yield response
19
20  result match
21    case Success(response) if response.statusCode == 200 =>
22      println("Accessed protected endpoint successfully!")
23      println(response.text())
24    case Success(response) =>
25      println(s"Request failed with status code: ${response.statusCode}")
26    case Failure(exception) =>
27      println(s"An error occurred: ${exception.getMessage}")

In this implementation, we use the dotenv-scala library to load our API key from a .env file, providing a more secure and maintainable way to manage sensitive credentials. The API key is then included in the headers of our request to the /todos endpoint, ensuring secure access to protected routes.

Throughout this lesson, we delved into the mechanics of API authentication using API keys and the role of HTTP headers in transmitting authentication information. The practical example demonstrated how to construct requests with API keys and handle responses appropriately using Requests-Scala. As you progress to the practice exercises, strive to experiment with different endpoints and variations of API key usage.

This lesson sets the stage for future discussions on more advanced authentication methods, such as sessions and JWT, which we will explore in the following lessons. Dive into the practice exercises now to solidify your understanding of accessing protected routes with API keys.