I’m currently looking at how exactly I can go about getting the information for the ingredient that I scan via the UPC scanner into the Ingreedyents software. I need an online database that will provide me with information like serving size, calories per serving, macronutrients per serving, etc.

So far, I’ve signed up for the Spoonacular API since they have a free service and the service offers both the UPC lookup that I want and the ingredient optimization based on a selection of ingredients.

I might take a whack at implementing a database for ingredients and populating it with scanned ingredients in the future but for now Spoonacular seems like a great way to get off the ground with this project.

I’ve written some basic code for making HTTPS requests with libcurl, but I quickly realized that I didn’t know enough about transfer protocols or website APIs to do this myself. So that’s what this post is about! Learning a bit more about APIs and how to interface with them.

Note: most of this information was paraphrased from this article at Smashing Magazine. The credit should go to that author. This is merely for personal purposes.

What is an API?

An API is an application programming interface and it provides a clean way to talk to someone else’s application from within your application. APIs are incredibly helpful for when you want to use functionality of another application but don’t want to or can’t include their source code (for many reasons).

In our case, we’re using Spoonacular’s API because we want to retrieve information that Spoonacular has in one of their databases. Spoonacular has to have some method of authenticating users for permissions and for managing payments. They do this by providing a “REST API” (we’ll get to that) that allows the user to authenticate themselves with an API Key. This API Key is unique to the user and thus provides a way to verify the user’s identity when making a request.

Well What’s a REST API, Then?

A REST API is an extremely common type of API for sending/receiving information on the internet. The “REST” in REST API stands for “Representational State Transfer”. This describes a set of guidelines to follow when the developers of the original application create the API we would like to use. One example the linked article gave is the rule that states the API user should get a piece of data when the user links to a specific URL. This is called a request/response where the request is the URL sent (along with some metadata) and the response is the data sent back to the user or client.

Structure of a Request

A request is broken down into four main parts:

1. The endpoint - the URL you request for which is comprised of the root-endpoint (https://api.github.com for example) and the path to the resource you’re requesting. Since one of the guidelines of REST APIs is that each URL is unique, the resource at the given endpoint will be the same each time a request is made (if it is successful, that it).
2. The method - one of GET, POST, PUT, PATCH, DELETE. I won’t get into the weeds with this but check out the linked article if you’d like more information.
3. The headers - headers are a way to provide information to both the user and the server.
4. The data or body - these are only used with POST, PUT, PATCH, OR DELETE requests so we won’t worry about them.

More on the Endpoint

The endpoint typically consists of the root-endpoint and the path, but I lied in saying that that is all they consist of. The final bit of the endpoint that we’re going to discuss in more detail are the query parameters. Query parameters aren’t technically part of the REST API guidelines but many APIs use them and they are worth discussing because that is how Spoonacular authenticates the user.

Query parameters are ways to modify the request with key-value pairs. They always begin with a question mark, ?, and each subsequent parameter is seperated with an ampersand, &.

For example, to supply the API key that Spoonacular requires for user authentication and to indicate that you would like to stick to a vegetarian diet when searching for recipes, you would use the following URL for the request:

https://api.spoonacular.com/recipes/search?diet=vegetarian&apiKey=<YOUR_API_KEY>

Conclusion

Well, that was a rather rapid introduction to REST APIs but I hope this is useful both down the road and to anyone else reading this.