Welcome back! Today's focus is on downloading files from an API. Understanding how to retrieve files efficiently not only enhances your technical skills but also broadens your application's capabilities. In this lesson, we'll explore a practical scenario using our To-Do list API, which, in addition to managing tasks, supports handling text files such as notes. These notes can be downloaded or uploaded through the /notes endpoint, allowing functionality for storing supplementary information. For example, users might keep notes about a meeting or important reminders. By understanding how to interact with this endpoint, you can effectively manage notes within your application. By the end of this lesson, you'll know how to request a file from an API, save it locally, and verify its contents.

Let's dive into downloading files with precision and confidence!

GET requests are essential for fetching resources from an API, which can include files. Using the httplib library in C++, when you perform a GET request, your client communicates with the server at a designated URL. In the context of our example, it explicitly requests a file when directed to the /notes endpoint with a file name like welcome.txt. The server, if it has the file and permissions are met, returns the file data along with an HTTP status code such as 200 OK.

Here's a basic example of downloading a file named welcome.txt from our API at http://localhost:8000/notes. This approach downloads the entire file at once, which is manageable for smaller files.

#include <iostream>
#include <fstream>
#include "httplib.h"

int main() {
    // Base URL for the API
    const std::string base_url = "http://localhost:8000";
    const std::string note_name = "welcome.txt";
    const std::string file_name = "downloaded_" + note_name;

    // Create an HTTP client
    httplib::Client cli(base_url.c_str());

    try {
        // Send a GET request to download the file
        auto res = cli.Get(("/notes/" + note_name).c_str());

        // Check if the request was successful
        if (res && res->status == 200) {
            // Open the local file in binary mode
            std::ofstream file(file_name, std::ios::binary);
            if (!file) {
                throw std::runtime_error("Failed to open file for writing");
            }

            // Write the response body to the file using << stream
            file << res->body;
            file.close();

            std::cout << "File downloaded successfully: " << file_name << std::endl;
        } else {
            std::cerr << "HTTP error occurred: " 
                      << (res ? std::to_string(res->status) : "No response") << std::endl;
        }
    } catch (const std::exception &e) {
        std::cerr << "Error occurred: " << e.what() << std::endl;
    }

    return 0;
}

This code sends a GET request and writes the full response content to a local file. This method works well for small files but can strain memory for larger files. The file is opened using std::ios::binary to ensure that no unintended transformations occur when writing the file. In text mode, some platforms (e.g., Windows) might modify newline characters (\n to \r\n), which can corrupt certain files, especially non-text files like images, PDFs, or executables. Using binary mode ensures that the data is written exactly as received.

When dealing with large files, downloading them all at once poses the risk of inefficient memory usage, which can lead to errors such as system crashes or application freezes. Without chunked downloading, a large file is loaded entirely into memory before processing. This can exceed available memory, particularly in systems with limited resources, resulting in memory allocation failures or application crashes. By using chunked downloads, you process and write each piece of data to a file as it arrives, significantly reducing the memory footprint and maintaining application responsiveness. This prevents memory overflow issues and enhances overall stability while handling large file sizes. The httplib library supports a callback mechanism that allows us to manage incoming data in smaller segments, which we can write to a file as received. This approach prevents memory overload and optimizes the downloading process for large files. Although the httplib library does not set an explicit chunk size, it processes incoming data as available, which can vary based on the network conditions and server response settings.

Here's an example using a callback to simulate chunked downloading for efficiency:

#include <iostream>
#include <fstream>
#include "httplib.h"

int main() {
    // Base URL for the API
    const std::string base_url = "http://localhost:8000";
    const std::string note_name = "welcome.txt";
    const std::string file_name = "downloaded_" + note_name;

    // Create an HTTP client
    httplib::Client cli(base_url.c_str());

    try {
        // Open the local file in binary mode
        std::ofstream file(file_name, std::ios::binary);
        if (!file) {
            throw std::runtime_error("Failed to open file for writing");
        }

        // Stream the response in chunks
        auto res = cli.Get(("/notes/" + note_name).c_str(),
            [&](const char *data, size_t data_length) {
                std::cout << "Received chunk of size: " << data_length << " bytes" << std::endl;
                file.write(data, data_length); // Write the chunk to the file
                return true; // Continue receiving more chunks
            });


        // Check if the request was successful
        if (!res) {
            throw std::runtime_error("Request failed: No response from server");
        }

        // Handle HTTP errors (4xx and 5xx)
        if (res->status >= 400) {
            std::cerr << "HTTP error occurred: " << res->status << std::endl;
            std::cerr << "Error message: " << res->body << std::endl;
            return 1;
        }

        file.close();
        std::cout << "File downloaded successfully: " << file_name << std::endl;
    } catch (const std::exception &e) {
        std::cerr << "Error occurred: " << e.what() << std::endl;
    }

    return 0;
}

By manually managing file writing, you can handle larger files more efficiently. This technique is especially useful as file sizes increase.

Once you've downloaded a file, it's important to verify its contents to ensure a successful transfer. In our example, after downloading, you can open the file and print a portion of its content to confirm data integrity:

#include <iostream>
#include <fstream>

int main() {
    const std::string note_name = "welcome.txt";
    
    // Open and read the downloaded file to verify its content
    std::ifstream file("downloaded_" + note_name);
    if (file.is_open()) {
        std::string content((std::istreambuf_iterator<char>(file)), (std::istreambuf_iterator<char>()));
        file.close();
        std::cout << content << "\n";
    } else {
        std::cerr << "File error occurred: Could not open the file.\n";
    }
    
    return 0;
}

This step is essential for data verification. The familiar error-handling techniques come into play once more, using simple checks to gracefully address any issues during the download and verification process.

In this lesson, you explored methods for downloading files from an API: a straightforward approach for smaller files and a simplified method for handling larger files. You've practiced verifying file integrity by reading its contents post-download and reinforced your knowledge of error management. As you proceed to the practice exercises, you'll have the opportunity to apply these skills, reinforcing your ability to manage API interactions effectively. Keep experimenting with different files and settings, as this will further enhance your understanding and proficiency. Exciting topics await, such as file uploads and handling paginated responses. Your journey in mastering API interactions continues!