Skip to main content

Intro

The aim of this project is to teach the fundamentals of building a Python API with OpenApi. The API itself is a pipeline API that uses the Star Wars Data at https://swapi.py4e.com/api/ and pass that through this API to clients. The openAPI enables the use of a Swagger definition and User interface. The definition acting as the definitive APi specification. The minimal use of the Python framework Flask in conjunction with Connexion are used to provide the bridge to our python API endpoints.

In order to complete this project you will need to clone/download the project from Github at StarWars API Learning Project

The project framework (.py) files on the repository are empty save for a couple of database configuration declarations in the config.v1.app_config.py file.

Apart from the base structure, there are several markdown files under training-docs and some setup files in the root. These documents are the same as you will see here and take the user through the setup and build process of the project step by step with explanations of the code.

The user is expected to copy and paste the code, by either following this version of the tutorial or the documents under training-docs on the GitHub repository. For setup information you should follow the instructions in the readme in the repository root directory.

The build process describes in detail all aspects of the project code-base without being over cumbersome. There is no time specification for building the project. More important than time is the understanding of the project architecture and what is going on in the code itself.

Before building this project the student must have at least a beginners understanding of Python, OpenAPI and APIs in general. An understanding of the http protocol is recommended. It is recommended that you study the "Developing for the Internet" course completely at Developing for the Internet. This course will provide you with the necessary knowledge to understand the technical aspects of this project.

Notes for those starting to learn about Software Development. Sometimes it feels impossible, sometimes it feels that there is too much to learn. Don't let these feelings stop you. You will have many breakthrough moments that will encourage you and provide a sense of achievement. Continue learning, it's what life is all about.

Notes for all those existing Python gurus. If you have any constructive comments and recommendations we would love to hear about them. The completed project without the learning tutorials is available on GitHub at StarWars API. To provide feedback on this course or contact us at Fathat.org, drop us a line at hello@fathat.org

Backend API Learning Workflow:​

Before you build the API start with the Project Structure to get a good understanding of where everything is and how the project is laid out.

Project Structure:

Welcome to the Star Wars backend API learning project. The project has a complete structure ready for you to start learning the process of building this backend. Before we begin building the backend, let's take a look at the structure in more detail.



Below is an image of the structure:

As you can see there are many folders, some of which are open and a bunch of files in the root.



Let's quickly go over the design of the API by looking at root files and the films folder.



The root files - all of which are empty except requirements.txt and the readme.md:

  • __init__.py - The root python initialisation file
  • basehandler.py - Will contain the main function required for any packaging of the responses to API requests back
  • main.py - Will contain the main python/flask module for running the API
  • openapi.yaml - Our APIs OpenAPI 3 definition document. This document will contain the specification for our API, all the rules for requests and responses shall be defined here along with all the parameters and where those parameters go for both requests and responses. It shall also contain our security definitions as to the type of authentication we may use.
  • readme.md - The main project readme file.
  • requirements.txt - The only file with content contains the package list required to run the API. You should have already run the requirements.txt file directly after creating your project virtual environment and selecting a python interpreter.
  • starwars.py - This file will contain our APIs handling of calls to the Star Wars API at 'https://swapi.py4e.com/api/'
  • utils.py - Will contain any utility classes or functions we made need.

Now let's look at the typical API structure using films.

  • v1 - this is used for versioning our API, v1=version1. At some point we may have a v2 folder, which contain the same files but with different code, a newer version. We can direct API requests to different versions, for example we may have v2 for characters but not for films, so we can direct all the character API requests to v2 of the character code. init.py - the python initialisation package for this folder.
  • data_access.py - Handles all the access to any data for films. Anything that touches our data and data source is defined in this file.

    Note we do not touch data in the endpoints methods. Why would we do this, well if we change our datasource, we modify that in this file and not in the endpoints, thus our endpoints do not have to change if we change our data source. It's about separation to help keep our code design as straight forward and robust as possible.

  • endpoints.py - Endpoints are the basis of our API calls and are linked to their relative functions via the openapi.yaml file. This file contains all the functions for our endpoints. The endpoint passes any requests for data to our data_access.py file which in turn passes any data to be returned to the client back to the endpoint. The endpoint then calls our basehandler which forwards the response back to the client through various other packages.
  • The other files are all ini.py files for python initialisation.

To get a feel for the flow of our API request and response check the simple data flow diagram below.


Finally let's look at the folders auth, config, database and errors.

  • auth - All the files for authentication and security for our API are here.
  • config - Any and all configuration such as database login details, security hashes used and anything else for configuration. This
  • database - All the database handling is done here. We use two types of database in this project, MySQL a sequel server database and Redis a no-sql database.
  • errors - This contains any error handling for the API.

That's it, so let's proceed to our build-1.md file under training-docs and get started.



Have Fun! :)

Building Our API​