Serving Models with a RESTful API

In the previous chapter, we discussed how to create dashboards. While one approach we took was to build a static, serverless web page, another required a server and the client parts of the application. In this chapter, we'll discuss the next logical step: providing programmatic access to your data and/or algorithms, via a RESTful API—similar to the ones we used in Chapter 9, Shell, Git, Conda, and More – at Your Command. An API is arguably the most ubiquitous and convenient way of delivering your service; it has few requirements for the consumer (essentially, an internet connection), is easy to publish and distribute, and can be constantly improved upon. Knowing how to build your own API is an essential skill for a developer.

The following topics will be covered in this chapter:

• What is a RESTful API?
• Building a basic API service...

Technical requirements

In this chapter, we'll use the following libraries:

• FastAPI
• pydantic
• uvicorn
• locust

Make sure to install them, if you haven't done so already. To test our API, we'll use the curl command-line tool. On Windows, you can install curl or use the built-in Invoke-Webrequest tool, aliased to wget.

Alternatively, you can use Postman, https://www.getpostman.com, a standalone and free application for testing and exploring web APIs with a nice graphical interface. To install Postman, go to the website and hit Get Started, then select Download. Postman has versions for Windows and Linux. Its interface is quite clean and easy to learn, so we won't cover it here.

All of the code is available in the GitHub repository, in the Chapter18 folder (https://github.com/PacktPublishing/Learn-Python-by-Building-Data-Science-Applications).

...

What is a RESTful API?

We worked with APIs before, in Chapter 9, Shell, Git, Conda, and More – at Your Command, as clients. So, it would be safe enough to assume we have some idea about an API: it is just an interface that allows us to exchange data with the service. Technically, APIs can use any protocol or means of communication, and there are plenty of applications with all types of interfaces. However, these days, when people say API, they likely mean RESTful API. Here, the REST part stands for Representational State Transfer. REST is based on six guiding architectural principles, but what is more important for us is that it is based around HTTP requests, similar to the ones our browsers execute when we type in a URL.

Behind each RESTful API is a server—or, most likely, a group of servers—ready to execute the command; this command could serve the entire...

Building a basic API service

A good practice is to start with something simple, where we don't risk having issues in our code—so we can test the framework, first. Let's start with a simple hello world application.

Let's dive in and start with a simple hello world-style application that will return the predefined values, with no computations at all:

1. First, we will need to import the library and initialize the main application object:

from fastapi import FastAPI
app = FastAPI()

2. Next, let's define our toy database:

db = {'noise': 24,
      'broken hydrant': 2}

3. We now define the function that will be executed for each URL request and return the value:

def complaints(complaint_type: str, hour:int) -> dict:
    return {"complaint_type": complaint_type, "hour": hour, "q": db.get(complaint_type, None)}

...

Building a web page

While FastAPI is focused on the APIs, it is still entirely possible to serve HTML pages as well. The code will be almost identical to the preceding code—except that our functions need to return this HTML code.

The most common approach to generate HTML in Python is to use the Jinja2 templating engine—that way, you write the template as an HTML code with some injections of Python and later render them by feeding it with the variables; Jinja will execute and hide the injections, returning the resultant page.

For the sake of building a simple example, however, we will use another package: VDOM, which allows us to generate VDOMs (short for Virtual Document Object Models) in Python and then convert them into HTML. Flask is great for smaller projects, but not for large and complex applications.

To separate this page from the main API, let's create...

Speeding up with asynchronous calls

Now, let's turn to the question of performance. Once in a while, our application will need to be constantly monitored and, if needed, scaled and optimized. There are a few ways to speed things up incrementally, for example, by installing the ujson package, which works exactly like built-in json but is more performant (because it is written in C). In that case, FastAPI will automatically switch to using this library instead.

Potentially, more significant improvement in performance is built into FastAPI, Uvicorn, and based on the new features of Python 3.4 and later versions, asynchronous calls. We did spend some time discussing this feature in Chapter 3, Functions. In a nutshell, all of the code we generally write in Python is executed sequentially—once one line is executed, Python will go to the next, and so on. It means that, when...

Deploying and testing your API loads with Locust

Once the application is deployed, but before it is publicly announced or used, it is a good idea to estimate how many requests it can handle. Usually, you can roughly predict the requirements for the service by estimating the number of requests it needs to execute at peak periods, how long those periods are, how fast it should respond, and so on. Once you're clear on the requirements, you'll need to test-load your application.

Test-loads should be performed on the actual, deployed server, not your localhost. Here, we skip over the whole topic of deploying your model. We also didn't use ngnix or any similar gateway servers, which would cache requests, boosting the performance of the API significantly. Deployment of the application deserves a separate book and can be achieved in many ways, depending on your existing...

Summary

In this chapter, we built our own API and deployed an ML model to send predictions as an endpoint. Using FastAPI's built-in features, we were able to generate interactive documentation and define a schema to validate both inputs and outputs. We further created a simple HTML dashboard, generating charts upon request, and we learned how to tune the performance of the API, leveraging asynchronous functionality. Lastly, we modeled a traffic load on our system, using an open source tool, Locust.

By doing so, we made a fast run over the full cycle of API development: choosing a framework, adding your business logic, and testing. The skills we learned along the way are useful if you want to get the flexibility, scalability, and richness of providing your service via an API.

Building your own web service is a great option—definitely the best if the API is popular and...

Questions

1. What is a RESTful API?
2. What Python packages can be used to build a RESTful API?
3. What are the key features of the FastAPI framework?
4. Why OpenAPI (Swagger)?
5. Why do we need Uvicorn or Gunicorn servers?
6. What metrics does the Locust package measure?

Further reading

• Building REST APIs with Python by Wayne Merry, published by Packt (https://www.packtpub.com/web-development/building-rest-apis-python-video)
• Building RESTful Python Web Services by Gaston C. Hillar, published by Packt (https://www.packtpub.com/application-development/building-restful-python-web-services)