We solve: A kick-start for the development of Web APIs

24.1.2023Jani Nevaranta, Full-stack -developerWe solve

Web APIs are an essential part of building a knowledge-based architecture. They allow information to be moved seamlessly from one system and environment to another, taking advantage of the movement of information across the web. So how is a Web API built? As the name suggests, in this article we will take a small-scale kick-off to the development of Web APIs and go through some of the first steps in their development.

An image drawn with markers showing a sketch of different ways to view data.
Source: Hal Gatewood, Unsplash.com.

Before we get our hands dirty so to speak, we need to define the needs and purpose of our Web API. Let's first unpack the kind of data our example API will eventually serve.

Let's imagine we have installed visitor counters at a quiet outdoor destination in the countryside. The counters count the number of people passing by them and record the time of day when the event occurred. Each counter is able to send the recorded number of people and the event times to the server at regular intervals. We want to use the visitor counters' measurement results for various analyses, which is why we need a Web API for real-time data transmission.

At first glance, it might seem that the task would be very simple - store the numbers sent by the counters in a database, from which the user can then use the API to pull the visitor data for each day. However, with a little extra effort, we can make it easier to clean up the data before the analysis part, and serve readily cleaned data neatly. The user of the API could therefore already have access to aggregated data with, for example, the following attributes:

  • Visitors on a single day
  • Visitors of a single counter
  • Visitors for a single week
  • And so on...

Providing and filtering data in this aggregated way makes it much easier for the API user to make use of the data - no need to crawl through each day individually. Ultimately, however, we want the correct information to find its final destination as straightforwardly as possible.

After designing the needs of our Web API, we can start working on the API itself. First, we need to choose the architectural model according to which standards we want to build the Web API. There are many options, but for this purpose we choose the very common RESTful architecture, which is well suited to the communication of numerical data.

Now that we have a rough idea of what kind of data we will get from the interface, what format it will be in and what standards we want to use to share it, we can start thinking about the so-called "endpoints" of the interface. In a RESTful architecture, data is imported from the interface and collected using the HTTP protocol via URIs. In everyday language, we can talk about importing and extracting data using a network address. So we define a path for each data collection and import address.

However, a network address or path alone is not enough; we also need to specify which HTTP method the network address path uses. There are different methods, but fortunately they are fairly unambiguous English words. Examples of HTTP methods supported by RESTful interfaces are GET, POST and PUT; GET retrieves data, POST modifies it and PUT adds new data to the API (these apply in most cases).

Once we have identified the needs of the API endpoints, we can proceed to compile them into, say, the functions given earlier as examples:

  • Visitors on a single day (day in the form day-month-year)
    • /visitors/day/01-01-2022, GET-metodi
  • Visitors for a single counter (each counter with its own ID number)
    • /visitors/counter/1, GET method
  • Visitors of the past week (week with week number)
    • /cavers/week/3, GET method

In addition to these, we can also define PUT methods separately, so we can use the same path but a different method to import new data to the database. Since counters are currently the only things that bring new data, we can define a PUT method on the /counter/ path to import counter data.

Finally, we want to decide which tools we will use to start building the API. For this purpose, we can use the open source programming framework FastAPI, which is built on top of the Python programming language and, as its name suggests, makes the development of simple Web APIs relatively fast and straightforward.

This has given us a good, albeit somewhat crude, starting point for Web API development. Of course, the design work should always be considered on a larger scale depending on the problem to be solved, but the framework we have created has given us a good start. Now let’s get our hands dirty!

Useful links for developing Web APIs:

SHARE ARTICLE

We solve

Read also