Writing an API Wrapper in C: The API Client
Welcome to the first blog in a series I will be calling Writing an API Wrapper in C. I’ll be talking about the API client in the first article.
API wrappers are extremely common as interfaces for data have moved from system libraries to the web. Libraries buy you first class language interaction with your data while web interfaces generally lack type checking like a compiler or interpreter would provide.
Enter API wrappers.
API wrappers represent first-class language contracts for interacting with data or services over the web. They allow you to use the niceties of your language of choice using an abstraction over a web interface.
Technologies I will be showcasing within the series include:
GLib- Expanded standard library for C.
GObject- Object-oriented type system for C. I could spend forever talking about this alone, but it wouldn’t really stay on topic. If you see anything confusing, email me or leave a comment.
libsoup- GLib-based HTTP library.
json-glib- JSON support for GLib.
You might be saying, “Tristan, but C lacks all the niceties that higher-level languages have so this feels like a waste of time.” And to that I say time is only wasted if you don’t see value. Let’s call this an exercise of the mind and dive right into the first topic in the series: Creating an API Client.
An API client is the object that will execute requests, and format responses into language constructs like objects and errors. Generally APIs will require some form of authentication along with any special headers that may need to be set. The Harvest API requires authentication, so I generated a developer token. It also requires a few other parameters, like an account ID, and a user agent including a contact email. Here is how I am creating a Harvest API client in C.
It would probably help to see a little bit of the definition of
These struct members and the request object I am given are all that I need to successfully make a request to the Harvest API. The API client has two public functions to be aware of.
You see the types
HarvestResponse in the code. We will
ignore that for now since it will be talked about later in the series. Just know
HarvestRequest includes the body, the HTTP method, the API endpoint, and
metadata about what constitutes a successful response, while
includes the deserialized response object, the error if there was one, and the
received status code.
We are good developers so we provide both an asynchronous and synchronous way to
use our client. Benefits of the synchronous API include blocking calls, while
the asynchronous API can benefit graphical interfaces or event loop style
programs where you react to events. The implementations of the execution
functions will be covered later when we talk about
HarvestResponse because they go hand in hand.
Hopefully this blog post was enough to trigger your interest in the series as there is more content to come.