API Development and Documentation

The application programming interface (API) is core to many technologies developers use to deal with data and facilitate communication between different systems. API-enabled digital business models are fast-growing. The need for experienced developers to build innovative enterprise solutions is equally on the rise.

The API economy is evolving into a new business model for sustainable business growth with a ton of opportunities for business owners and smart executives. If there were ever a time to be a developer, it would be now, with the plethora of public APIs and valuable commercial APIs that can make application development and deployment achievable with less effort.

Previously in this book, we discussed how databases and data modeling can be used to effectively store and retrieve application data as required. This chapter presents the opportunity to dive into the heart of backend development and leverage API technology to enable seamless...

Technical requirements

The complete code for this chapter is available on GitHub at: https://github.com/PacktPublishing/Full-Stack-Flask-and-React/tree/main/Chapter09.

What is an API?

API stands for application programming interface. On the surface, an API seems like another piece of technical jargon coined to make learning application development difficult. This is not the case. An API’s core purpose is to facilitate communication between different systems based on an agreed set of rules, methods, and protocols.

In the context of web applications, an API helps omnichannel frontend applications to communicate with backend services. The growing demand for digital services is fueling innovative ideas from business organizations to make their digital assets available through the design and implementation of APIs.

As a developer, you are going to spend a great chunk of your time developing solutions that are API-driven. Knowing how to design and implement API solutions increases your skill capital and value to your employer. Broadly speaking, there are two types of APIs: private APIs and public APIs.

Private APIs are sometimes called...

Why use an API in web development

APIs are an integral part of modern web application development. You will rarely come across a data-driven web app without some form of API implementation. The reason why APIs are so popular is not difficult to see. APIs enable seamless integration, collaboration, and innovation by providing standardized ways to facilitate efficient resource sharing across diverse applications and systems. The following are some of the benefits of the use of APIs in web development:

• APIs allow separate systems to interact, bridging communication gaps between different components of web applications
• API-driven development enables access to third-party data and services, fostering innovative solutions and reducing development time
• APIs provide a secure and scalable means of sharing information for developers and end users
• API-centric development reduces software development time by leveraging existing APIs and avoiding reinventing the wheel
• APIs...

Endpoint and payload anatomy

Endpoints and payloads are a crucial part of any API component. Endpoints facilitate access to resources on a server through the use of well-defined routes or URLs. Endpoints usually act as the actual point at which data exchange occurs between two disparate applications in a client-server environment. Payloads allow us to send data along with a request or a response. We will discuss more on payloads in a jiffy.

Let’s start by examining the structure of an endpoint and the rules guiding endpoints set up in a REST API.

Understanding the endpoint structure

Endpoint structures allow you to logically organize the resources of your application. We are going to start with a venue resource in exploring endpoint structure. Data is usually represented as resources in a REST API. You can define an endpoint for a venues collection with a venue resource following the use of the collection/resource path convention.

Note

The venue resource represents...

Understanding HTTP requests/responses

To successfully work with APIs, you need to have an understanding of HTTP requests/responses. So, let’s unmask the structure of HTTP requests and responses.

Request line

Every HTTP request begins with the request line. This comprises the HTTP method, the requested resource, and the HTTP protocol version:

GET /api/v1/venues  HTTP/1.1

In this instance, GET is the HTTP method, /api/v1/venues is the path to the resource requested, and HTTP 1.1 is the protocol and version used.

Let’s dive deeper into HTTP methods to understand how developers use different HTTP methods to specify the type of action they want to perform when making requests to the web servers.

HTTP methods

HTTP methods indicate the action that the client intends to perform on the web server resource. Commonly used HTTP methods are the following:

• GET: The client requests a resource on the web server
• POST: The client submits data...

Understanding HTTP status codes

HTTP status codes are three-digit numbers sent by a server in response to an HTTP request. These codes provide feedback to the client about the outcome of the request and help identify any issues that may have occurred during the transaction. The first digit of an HTTP status code indicates the category of the responses, which could be Informational, Successful, Redirection, Client Error, or Server Error.

The common status codes you’ll encounter for each category are listed as follows:

1XX Informational

Status Code	Description	Reason
100	This code indicates an interim response from the web server informing the client to continue the request or ignore the response if the request has already been processed	Continue

2XX Successful

...

REST API design principles

REST API, or RESTful API, describes an API that conforms to the REST architectural style using an HTTP-based interface for network communication. An API in its simplest form defines a set of rules that disparate systems or applications need to conform to in order to exchange data.

Dr. Roy Fielding, in the year 2000, presented a dissertation (https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) that described a novel design approach that API designers are expected to follow in building applications that can stand the test of time in addition to being secure. In order to develop a RESTful system, there are architectural constraints that are worth keeping in mind.

We will examine those REST principles, such as client-server, statelessness, caching, uniform interface, layered system, and code on demand, to conform to a REST style guide.

Client-server

The REST API architecture encourages client and server communication. The client...

Implementing a REST API in a Flask application

Flask, as a popular Python web framework, provides developers with a flexible and lightweight solution for building web applications. With Flask, you can easily create and manage RESTful APIs. The process of implementing a REST API in a Flask application is simple.

Implementing a REST API in a Flask application involves defining API endpoints, request handlers, and data models, and possibly connecting to a database. In this section, we are going to design a REST API service using Flask that a React frontend application can consume.

We will follow a simple process of defining the resources expected in the Bizza application, following which we will define the URLs (endpoints) that would be used to access the resources. In addition, we will use Flask’s routing system to map each endpoint to a specific function in the application.

Each function should handle the HTTP request, interact with the database (if necessary), and return...

API interaction with a database via CRUD operations

In most web application projects, it is common to work with databases for the purpose of persistent data storage. You won’t be hardcoding plain text into your REST API, unless you are that person who tries to boil the ocean.

CRUD, an acronym for create, read, update, and delete, allows you to manage the state of resources in the database. Interestingly, each of the CRUD elements can also be mapped to the HTTP methods—GET, POST, PUT/PATCH, and DELETE – which further describes and facilitates the interaction with the database.

In a full stack web application, you expect your users to able to create a resource (POST or PUT if it is an existing resource), read a resource (GET), update a resource (PUT/PATCH), and delete a resource (DELETE). In this section, we will work with a simple venue resource with the following endpoints, and the HTTP operations we will perform on them are CRUD.

All the code for the...

API documentation

Have you ever tried to assemble a piece of equipment you bought from a store without looking through the manual? There is a high probability you will have done so deliberately. You smartly think it will be easy to put together, and most times, you get burned in this process of trial and error and eventually mess things up.

Manuals are a good resource meant to ease you through a product’s features and functionality. API documentation is no different from manuals for guidance, a set of instructions, references, or even tutorial materials that can enhance developers’ understanding of your API.

Why is API documentation a critical component of your API? We will examine a few reasons and dive into using the Postman client tool to document your API so that other developers can understand what it is all about and how to use it. We will use a very simplistic case study with the venues CRUD operation we examined in the preceding section.

In a production...

Testing and documenting with Postman

Postman is an advanced API platform that provides a range of features to simplify the development, testing, and utilization of APIs. Postman offers a user-friendly interface for testing API endpoints, generating API documentation, and collaborating on API-related operations.

To begin using Postman, you can download and install the application on your local machine. Visit the official Postman website at https://www.postman.com/downloads to access the download page. From there, you can choose the appropriate version for your operating system and follow the installation instructions.

Once you have Postman installed, you can leverage the power of Postman to document RESTful API endpoints, execute requests, analyze responses, and perform comprehensive testing.

Let’s leverage venues on the collections and generate API documentation that tells other developers how to make requests and describe the response to expect:

1. On your computer...

Summary

In this chapter, we explored API development in Flask applications. We started by understanding what an API is all about and why businesses and developers are creating and consuming APIs to drive their data access. We took things further by taking a quick run through common terminologies developers come across when implementing the API design pattern.

Then, we unmasked the structure of endpoints and payloads, recognizing that designing routes and exchanging data form the foundational elements of API development. In addition, we critically examined the design principles guiding RESTful API development. We discussed how understanding the REST API design principles enhances best practices in API design and development. Also, we discussed the implementation of the REST API and how we can connect API backend services with a database in a Flask application.

Finally, we discussed API testing and documentation with Postman. In API design and development, we recognized how testing...

The rest of the chapter is locked

REST API design principles

REST API, or RESTful API, describes an API that conforms to the REST architectural style using an HTTP-based interface for network communication. An API in its simplest form defines a set of rules that disparate systems or applications need to conform to in order to exchange data.

Dr. Roy Fielding, in the year 2000, presented a dissertation (https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) that described a novel design approach that API designers are expected to follow in building applications that can stand the test of time in addition to being secure. In order to develop a RESTful system, there are architectural constraints that are worth keeping in mind.

We will examine those REST principles, such as client-server, statelessness, caching, uniform interface, layered system, and code on demand, to conform to a REST style guide.

Client-server

The REST API architecture encourages client and server communication. The client...

Implementing a REST API in a Flask application

Flask, as a popular Python web framework, provides developers with a flexible and lightweight solution for building web applications. With Flask, you can easily create and manage RESTful APIs. The process of implementing a REST API in a Flask application is simple.

Implementing a REST API in a Flask application involves defining API endpoints, request handlers, and data models, and possibly connecting to a database. In this section, we are going to design a REST API service using Flask that a React frontend application can consume.

We will follow a simple process of defining the resources expected in the Bizza application, following which we will define the URLs (endpoints) that would be used to access the resources. In addition, we will use Flask’s routing system to map each endpoint to a specific function in the application.

Each function should handle the HTTP request, interact with the database (if necessary), and return...

API interaction with a database via CRUD operations

In most web application projects, it is common to work with databases for the purpose of persistent data storage. You won’t be hardcoding plain text into your REST API, unless you are that person who tries to boil the ocean.

CRUD, an acronym for create, read, update, and delete, allows you to manage the state of resources in the database. Interestingly, each of the CRUD elements can also be mapped to the HTTP methods—GET, POST, PUT/PATCH, and DELETE – which further describes and facilitates the interaction with the database.

In a full stack web application, you expect your users to able to create a resource (POST or PUT if it is an existing resource), read a resource (GET), update a resource (PUT/PATCH), and delete a resource (DELETE). In this section, we will work with a simple venue resource with the following endpoints, and the HTTP operations we will perform on them are CRUD.

All the code for the...

API documentation

Have you ever tried to assemble a piece of equipment you bought from a store without looking through the manual? There is a high probability you will have done so deliberately. You smartly think it will be easy to put together, and most times, you get burned in this process of trial and error and eventually mess things up.

Manuals are a good resource meant to ease you through a product’s features and functionality. API documentation is no different from manuals for guidance, a set of instructions, references, or even tutorial materials that can enhance developers’ understanding of your API.

Why is API documentation a critical component of your API? We will examine a few reasons and dive into using the Postman client tool to document your API so that other developers can understand what it is all about and how to use it. We will use a very simplistic case study with the venues CRUD operation we examined in the preceding section.

In a production...

Testing and documenting with Postman

Postman is an advanced API platform that provides a range of features to simplify the development, testing, and utilization of APIs. Postman offers a user-friendly interface for testing API endpoints, generating API documentation, and collaborating on API-related operations.

To begin using Postman, you can download and install the application on your local machine. Visit the official Postman website at https://www.postman.com/downloads to access the download page. From there, you can choose the appropriate version for your operating system and follow the installation instructions.

Once you have Postman installed, you can leverage the power of Postman to document RESTful API endpoints, execute requests, analyze responses, and perform comprehensive testing.

Let’s leverage venues on the collections and generate API documentation that tells other developers how to make requests and describe the response to expect:

1. On your computer...

Summary

In this chapter, we explored API development in Flask applications. We started by understanding what an API is all about and why businesses and developers are creating and consuming APIs to drive their data access. We took things further by taking a quick run through common terminologies developers come across when implementing the API design pattern.

Then, we unmasked the structure of endpoints and payloads, recognizing that designing routes and exchanging data form the foundational elements of API development. In addition, we critically examined the design principles guiding RESTful API development. We discussed how understanding the REST API design principles enhances best practices in API design and development. Also, we discussed the implementation of the REST API and how we can connect API backend services with a database in a Flask application.

Finally, we discussed API testing and documentation with Postman. In API design and development, we recognized how testing...