Tutorial: Building a RESTful API with Flask

In this tutorial, we’ll be learning and creating RESTful APIs with Flask. To follow along with this tutorial, you should already have a good grasp of Python, Flask, and SQLAlchemy.

Since the application we’re going to build in this article is an extension of the one we built earlier in the Flask SQLAlchemy Tutorial, make sure you’ve already read that post and have the code available for our API additions!

What is an API?

API is one of those technical terms that gets thrown around a lot in the programming world. We hear about people creating applications using Uber APIs or Google Map APIs. For example, I created a job search application using Twitter’s API. But what exactly is an API, and why is it so important?

API stands for Application Programming Interface, and it refers to the mode of communication between any two software applications. An API is just a medium that lets two entities of code talk to each other.

Have you ever implemented Google Maps in your application or have seen an app that makes use of Google Maps? That’s the Google Maps API.

Watch this tutorial to see the Twitter API in action:

Companies like Google and Facebook, among many others, have APIs that allow external applications to use their functionalities without exposing their codebase to the world. There’s a high chance that an organization you want to work with already has an API in place – both for developers and end users.  

But why do companies allow us to use their content via APIs? By allowing users access to their content, businesses add value for developers and users alike. Instead of building a new functionality from scratch and re-inventing the wheel, developers can use existing APIs and focus on their primary objectives. This practice actually helps organizations by building relationships with developers and growing their user base.

Now that we have a grasp on APIs, let’s talk about REST.

What is REST?

Like API, REST is an acronym, and it stands of Representational State Transfer. It’s an architectural style for designing standards between computers, making it easier for systems to communicate with each other. In simpler terms, REST is a set of rules developers follow when they create APIs. A system is called RESTful when it adheres to these constraints.

To better understand RESTful APIs, we need to define what the terms “client” and the “resource” mean.

Client: A client can refer to either a developer or software application which uses the API.  When you are implementing the Google Maps API in your application, you are accessing resources via the API, which makes you a client. Similarly, a web browser can also be a client.

Resource: A resource describes an object, data, or piece of information that you may need to store or send to other services. For example, the location coordinates you receive when you work with Google Maps API are a resource.

So, when a client sends a request to the server, it receives access to a resource. But what language do clients and servers use?

For humans to speak to each other, we have proper syntax and grammar. Without them, it’s impossible to understand what’s being communicated. Similarly, APIs have a set of rules for machines to communicate with each other that are called Protocols.

HTTP and requests

HTTP is one of the protocols that allows you to fetch resources. It is the basis of any data transfer on the Web and a client-server protocol. RESTful APIs almost always rely on HTTP.

When we are working with RESTful APIs, a client will send an HTTP request, and the server will respond with the HTTP response. Let’s dig into what HTTP requests and HTTP responses entail.

When an HTTP request is sent to the server, it usually contains the following:

  1. A header
  2. A blank line that separates the header with the body
  3. An optional body

The header consists of an HTTP verb, URI and an HTTP version number which is collectively called a request line.

GET /home.html HTTP/1.1

In the above example, GET is an HTTP verb, home.html is a URI where we want to get the data from, and HTTP/1.1 refers to the HTTP version.

GET isn’t the only HTTP verb out there, so let’s look at some of the other HTTP verbs commonly used.

  • GET: The GET method is only used to retrieve information from the given server. Requests using this method should only recover data and should have no other effect on the data.
  • POST: A POST request is used to send data back to the server using HTML forms.
  • PUT: A PUT request replaces all the current representations of the target resource with the uploaded content.
  • DELETE: A DELETE request removes all the current representations of the target resource given by URI.
Back to Top