Consuming APIs in C: a practical guide for modern developers

Today, consuming web APIs is a common practice for exchanging data between applications. Tutorials on consuming APIs in languages like JavaScript, Python, or PHP are plentiful, but C—often associated with system-level programming—is rarely considered for this purpose. However, C is perfectly capable of handling API requests, making it a viable choice for scenarios like Point of Sale (PoS) systems, IoT devices, or embedded applications, where C is already used for its efficiency and low-level control.

This article explores how to consume APIs in C, leveraging the libcurl library. By the end, you'll understand how to fetch and process data from APIs using C, and why this approach is relevant even in modern development.

Why use C for consuming APIs?

While higher-level languages dominate web development, C is still a practical choice for consuming APIs in specific use cases:

• Performance: C provides high performance and minimal overhead, making it suitable for resource-constrained environments like IoT devices.
• Control: direct memory management allows fine-tuned optimization, especially for embedded systems.
• Interoperability: C’s widespread use means it integrates well with system-level operations, such as controlling hardware, sensors, or other peripherals.
• Longevity: applications built in C often have long lifespans, especially in industries like retail or manufacturing.

Introducing libcurl: the tool for HTTP in C

To consume APIs in C, libcurl is the go-to library. It’s an open-source, portable, and feature-rich library for handling network requests over HTTP, HTTPS, FTP, and more. It supports:

• Making GET, POST, and other HTTP requests.
• Handling headers and authentication.
• Processing responses efficiently.

Basic steps for consuming an API in C

Let’s walk through the process of consuming an API using C, focusing on a real-world example of fetching JSON data.

Setup and installation

To use libcurl, you need to install it on your system. For most Linux distributions, this can be done with:

sudo apt-get install libcurl4-openssl-dev

On Windows, you can download precompiled binaries from the libcurl website: https://curl.se/download.html

On macOS if you use Homebrew you can install it via

brew install curl

Structuring your C program

A simple C program to fetch data from an API involves the following components:

• Initializing libcurl.
• Configuring the API request (URL, HTTP method, headers, etc.).
• Receiving and storing the response.
• Cleaning up resources.

Here’s an example program to fetch JSON data from a public API:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <curl/curl.h>

// Struct to hold response data
struct Memory {
    char *response;
    size_t size;
};

// Callback function to handle the data received from the API
static size_t ResponseCallback(void *contents, size_t size, size_t nmemb, void *userp) {
    size_t totalSize = size * nmemb;
    struct Memory *mem = (struct Memory *)userp;

    printf(". %zu %zu\n", size, nmemb);
    char *ptr = realloc(mem->response, mem->size + totalSize + 1);
    if (ptr == NULL) {
        printf("Not enough memory to allocate buffer.\n");
        return 0;
    }

    mem->response = ptr;
    memcpy(&(mem->response[mem->size]), contents, totalSize);
    mem->size += totalSize;
    mem->response[mem->size] = '\0';

    return totalSize;
}

int main() {
    CURL *curl;
    CURLcode res;
    struct Memory chunk;

    chunk.response = malloc(1);  // Initialize memory
    chunk.size = 0;             // No data yet

    curl_global_init(CURL_GLOBAL_DEFAULT);
    curl = curl_easy_init();

    if (curl) {
        // Set URL of the API endpoint
        char access_token[] = "your-access-token";
        char slug[] = "home";
        char version[]= "draft";
        char url[256];
        snprintf(url, sizeof(url), "https://api.storyblok.com/v2/cdn/stories/%s?version=%s&token=%s", slug, version, access_token);

        // Print the URL
        printf("URL: %s\n", url);

        // initializing libcurl

        // setting the URL
        curl_easy_setopt(curl, CURLOPT_URL, url );

        // Follow redirect
        curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);

        // Set callback function to handle response data
        curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, ResponseCallback);

        // Pass the Memory struct to the callback function
        curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *)&chunk);

        // Perform the HTTP GET request
        res = curl_easy_perform(curl);

        // Check for errors
        if (res != CURLE_OK) {
            fprintf(stderr, "curl_easy_perform() failed: %s\n", curl_easy_strerror(res));
        } else {
            printf("Response data size: %zu\n", chunk.size);
            //printf("Response data: \n%s\n", chunk.response);
        }

        // Cleanup
        curl_easy_cleanup(curl);
    }

    // Free allocated memory
    free(chunk.response);

    curl_global_cleanup();
    return 0;
}

Steps to run

Save the code in a file, e.g., get.c.
Compile it with the following command:

gcc get.c -o get -lcurl

Run the compiled program:

./get

Understanding the callback mechanism in HTTP responses with libcurl

When working with libcurl to handle HTTP responses in C, it’s important to understand the behavior of the callback function. The callback function you define to process the response data, such as the ResponseCallback function, may be invoked multiple times for a single HTTP response. Here’s why and how this works.

Why is the callback invoked multiple times?

The callback mechanism in libcurl is designed to handle data efficiently and flexibly. Instead of waiting for the entire response to be downloaded before processing it, libcurl processes the response in smaller chunks, calling your callback function as each chunk is received.

This behavior allows:

• Efficient Memory Usage: by processing chunks incrementally, you avoid the need to allocate a large block of memory upfront for the entire response.
• Streamed Processing: you can process or act on each chunk as it arrives, which is useful for streaming large responses or handling data in real-time.

How Does It Work?
Each time a chunk of data is received from the server, libcurl calls your callback function. The size of each chunk depends on network conditions, buffer sizes, and libcurl’s internal logic.
The callback has to accumulate the chunks, ultimately reconstructing the full response.

Here’s an example sequence:

1. The server starts sending the response.
2. libcurl receives the first chunk and calls the callback.
3. The callback processes or stores the chunk.
4. libcurl receives the next chunk and calls the callback again.
5. This process continues until the entire response is received.

Step-by-Step source code explanation for ResponseCallback function

The ResponseCallback is the function called when data is received by libcurl.

Function Declaration

static size_t ResponseCallback(void *contents, size_t size, size_t nmemb, void *userp)

• void *contents: this is a pointer to the data received from the server. libcurl provides this buffer and fills it with the data it downloads.
• size_t size and size_t nmemb: These represent the size of each memory block (size) and the number of blocks (nmemb). Together, size * nmemb gives the total size of the data received in this chunk.
• void *userp: this is a user-defined pointer passed to the callback function via curl_easy_setopt(curl, CURLOPT_WRITEDATA, ...). In this example, it's a pointer to a struct Memory object, which stores the full response.

Calculate total data size

size_t totalSize = size * nmemb;

This computes the total size of the current chunk of data received by multiplying the size of one block (size) with the number of blocks (nmemb).
For example, if the server sends 8 blocks of 256 bytes each, totalSize will be 8 * 256 = 2048 bytes.

Access user data (struct Memory)

struct Memory *mem = (struct Memory *)userp;

The userp pointer is cast to a struct Memory *. This struct was passed earlier in the main program and is used to accumulate the received data.

The struct Memory is defined as:

struct Memory {
    char *response;
    size_t size;
};

• response: a dynamically allocated string that stores the downloaded data.
• size: the current size of the response string.

Reallocate memory

char *ptr = realloc(mem->response, mem->size + totalSize + 1);

Resizes the response buffer to accommodate the new data chunk:

• mem->size: the current size of the buffer.
• totalSize: The size of the new chunk.
• +1: Space for the null-terminator (\0) to make it a valid C string.
• realloc: dynamically reallocates memory for the response buffer.

If the allocation fails, realloc returns NULL, and the old memory remains valid.

Handle memory allocation errors

if (ptr == NULL) {
    printf("Not enough memory to allocate buffer.\n");
    return 0;
}

If memory allocation fails (so ptr is NULL), print an error message and return 0. Returning 0 signals libcurl to abort the transfer.

Update the buffer

mem->response = ptr;
memcpy(&(mem->response[mem->size]), contents, totalSize);

• mem->response = ptr: assign the newly allocated memory back to the response pointer.
• memcpy: copy the new chunk of data from contents into the buffer:
  • &(mem->response[mem->size]): The location in the buffer where the new data should be appended (end of the current data).
  • contents: The data received from the server.
  • totalSize: The size of the data to copy.

Update the total size

mem->size += totalSize;

Increment the size of the response buffer to reflect the new total size after appending the new chunk.

Null-Terminate the response string

mem->response[mem->size] = '\0';

Add a null-terminator at the end of the response buffer to make it a valid C string.
This ensures that the response can be safely treated as a regular null-terminated string.

Return the total size

return totalSize;

Return the number of bytes processed (totalSize).
This signals to libcurl that the data chunk was handled successfully.

When to choose C for APIs

Use C for consuming APIs when:

• Performance Matters: C is ideal for speed-critical applications.
• System Integration: you need to combine network requests with hardware operations (e.g., fetching data for a PoS system).
• Embedded Systems: resource-constrained devices benefit from C’s efficiency.
• Curiosity and exploration: Sometimes, you use C simply because you enjoy programming and want to challenge yourself by exploring a lower-level language for tasks often reserved for higher-level ones. It’s a great way to deepen your understanding of how things work under the hood!

Conclusion

Consuming APIs in C might seem unconventional in today’s high-level programming world, but it’s a powerful tool for scenarios requiring performance, control, and integration with system-level operations. By using libraries like libcurl, developers can easily integrate HTTP requests into C applications, bridging the gap between modern APIs and traditional system-level programming.

With this knowledge, you can build C applications that interact seamlessly with APIs, proving that C remains relevant even in modern development workflows.