Welcome to the second lesson in our journey of interacting with APIs using Scala 3 and the Requests-Scala library. In the previous lesson, we laid a strong foundation for understanding RESTful APIs and how HTTP requests facilitate interactions with them. We used curl to manually send a GET request to an endpoint. Now, we are transitioning to automating this process using Scala. This lesson introduces Requests-Scala, which allows us to send HTTP requests effortlessly in our Scala applications, making it an invaluable tool in the realm of web development and API integration.

To make HTTP requests in Scala, we use the Requests-Scala library, which provides a simple and powerful API for handling HTTP requests. To get started, you'll need to add the following dependencies to your build.sbt file:

sbt
Copy to clipboard
1libraryDependencies += "com.lihaoyi" %% "requests" % "0.6.9"
2libraryDependencies += "com.lihaoyi" %% "ujson" % "3.1.3"

Once the dependencies are added, you can import the necessary packages in your Scala code, making their functionalities available for sending HTTP requests and handling JSON:

Scala
Copy to clipboard
1import requests.*
2import ujson.*

With this setup, you'll be equipped to automate requests, saving time and boosting efficiency in your development workflow.

When interacting with an API, it's helpful to define a base URL for the service you're communicating with. This makes your code more modular and easy to maintain, allowing you to change the root of your API URL in one place without modifying each request.

Scala
Copy to clipboard
1// Base URL for the API
2val baseUrl = "http://localhost:8000"

By setting this baseUrl, we can easily concatenate endpoints for different services within the API, making our code cleaner and more adaptable.

Let's dive into the process of fetching data from an API using Scala's Requests-Scala library. Our goal is to retrieve a list of to-do items from the /todos endpoint using the GET method.

Scala
Copy to clipboard
1// Fetch all todos using the get method
2val responseTry = Try(requests.get(s"$baseUrl/todos"))
3
4// Handle response success or failure
5responseTry match {
6  case Success(response) =>
7    // Print raw response
8    println("Raw Response:")
9    println(response.text())
10
11    // Continue with response handling based on status codes ...
12  case Failure(exception) =>
13    println(s"Failed to fetch todos: ${exception.getMessage}")
14}

By using the requests.get() method, we send a GET request to the constructed full URL. The response from the server, stored in the variable response, is then printed using response.text(), which gives us the raw response body as a string.

Here's an example of what the raw response might look like:

Plain text
Copy to clipboard
1Raw Response:
2[
3  {
4    "description": "Milk, eggs, bread, and coffee",
5    "done": false,
6    "id": 1,
7    "title": "Buy groceries"
8  },
9  {
10    "description": "Check in and catch up",
11    "done": true,
12    "id": 2,
13    "title": "Call mom"
14  },
15  {
16    "description": "Summarize Q4 performance metrics",
17    "done": false,
18    "id": 3,
19    "title": "Finish project report"
20  },
21  {
22    "description": "30 minutes of cardio",
23    "done": true,
24    "id": 4,
25    "title": "Workout"
26  }
27]

This raw output allows us to see the immediate result returned by the server, serving as a starting point for further processing of the data.

To determine the outcome of an HTTP request, we use the statusCode attribute of the response object to check the status code returned by the server. When the server responds with a status code of 200, it signifies a successful interaction, meaning the server has correctly processed the request and returned the expected data. In such cases, we can confidently parse the body in the desired format, which is JSON in our case.

Scala
Copy to clipboard
1responseTry match {
2  case Success(response) if response.statusCode == 200 =>
3    println("Todos retrieved successfully:")
4    val todos = ujson.read(response.text())
5    for todo <- todos.arr do
6      println(s"Title: ${todo("title").str}, Description: ${todo("description").str}, Done: ${todo("done").bool}")
7  // Handle other cases ...
8}

It's important to keep in mind that while a 200 status code confirms a successful request, you should still validate the response content - the server might return an empty dataset or partial results due to pagination (We'll explore this in the upcoming units!).

Here is an example of what you might see when the request is successful:

Plain text
Copy to clipboard
1Todos retrieved successfully:
2Title: Buy groceries, Description: Milk, eggs, bread, and coffee, Done: false
3Title: Call mom, Description: Check in and catch up, Done: true
4Title: Finish project report, Description: Summarize Q4 performance metrics, Done: false
5Title: Workout, Description: 30 minutes of cardio, Done: true

By leveraging ujson for JSON parsing, we can efficiently extract and work with the data returned by the server, making our scripts more intuitive and powerful.

Errors can happen on either the client or server side, so it's important to handle them properly. A 400 status code means there was a mistake in the request, often due to incorrect syntax from the client side. To understand these errors better, you can print the response body as JSON, which provides more details about what went wrong and can help you fix the issue.

Scala
Copy to clipboard
1case Success(response) if response.statusCode == 400 =>
2  println("\nBad Request. The server could not understand the request due to invalid syntax.")
3  val error = ujson.read(response.text())
4  println(s"Error Details: $error")

A 401 status code indicates an unauthorized request, often due to missing or invalid credentials. This situation requires the user to address authentication problems to proceed.

Scala
Copy to clipboard
1case Success(response) if response.statusCode == 401 =>
2  println("\nUnauthorized. Access is denied due to invalid credentials.")
3  val error = ujson.read(response.text())
4  println(s"Error Details: $error")

When encountering a 404 status code, it means the requested resource is not found, often pointing to a missing resource or an incorrect endpoint.

Scala
Copy to clipboard
1case Success(response) if response.statusCode == 404 =>
2  println("\nNot Found. The requested resource could not be found on the server.")
3  val error = ujson.read(response.text())
4  println(s"Error Details: $error")

A 500 status code reflects an internal server error, indicating the server encountered an unexpected situation. Such cases usually require investigation on the server side to resolve the issue.

Scala
Copy to clipboard
1case Success(response) if response.statusCode == 500 =>
2  println("\nInternal Server Error. The server has encountered a situation it doesn't know how to handle.")
3  val error = ujson.read(response.text())
4  println(s"Error Details: $error")

For responses falling outside the common codes, a generic approach captures these cases, ensuring all responses are analyzed for potential issues.

Scala
Copy to clipboard
1case Success(response) =>
2  println(s"\nUnexpected Status Code: ${response.statusCode}")
3  val error = ujson.read(response.text())
4  println(s"Error Details: $error")

By handling these diverse status codes, we ensure robust API interactions and better understand the server's communication.

In this lesson, we've explored the powerful capability of Scala's Requests-Scala library to make GET requests to an API. We've seen how to retrieve and handle responses effectively, interpreting HTTP status codes to understand the server's communication. This knowledge is crucial for creating reliable interactions with APIs. As you move on to the practice exercises, focus on experimenting with the code snippets and handling various status codes to solidify your understanding. In future lessons, we will build on this foundation, unlocking the potential to perform more complex tasks like updating and manipulating API data. Keep up the great work as you advance through the course!