This is part one of a series about developing and testing a simple REST interface. Code can be cloned or viewed from https://github.com/tscott8706/restexample.
I encourage you to follow along in this series if you want to learn any of the following:
- TDD or unit testing in general
- REST implementation using Python
- My normal development process – this is the process I use to develop code, as well as my thought process!
What Is REST?
If you are unfamiliar with REST, there are several resources out there that will teach you about it. I will just give the layman’s version. REST works on things called “resources”. Resources generally operate with CRUD operations (create/read/update/delete) on a database. In order to do things with these resources, we send an HTTP request to the server hosting that REST interface, and the server takes some action based on the request.
For this code example, one resource we have is a person (at least at the time of this writing). At this time, the person only has a name and a birth date. That means when we create a new person, we need to provide both those things. A create operation is called “POST”.
In order to get any people that we have created, we use an operation called “GET”. Depending on arguments that you pass into a GET request, it can get information about a single person or multiple people.
Those CRUD operations usually map directly to database operations… creating, reading, updating, or deleting something from a database.
REST Example Implementation
For this example project, I’ve chosen to use Flask as the web server (a Python web server framework) and MongoDB as the database that will store resources. It has a Python package directory structure and can be installed as a Python package. Communication with MongoDB will be through the Flask-PyMongo library. I chose to launch both the restexample and Mongo database within separate Docker containers (in order to keep the environment consistent). These are located within a docker-compose.yml file.
In order to test the project, I am using two separate docker-compose.yml files. One is for unit testing, and I used this a whole lot (using a TDD approach as I describe in a previous post). The other docker-compose file is for system testing. I did not look into this type of testing until I had at least one resource to create and get (the Person resource). At the time of this writing, that system test does not yet pass (I haven’t learned the framework it uses yet). It uses a library called pyresttest, which is an automated framework in Python to test REST APIs.
One key point I want to raise here: I spent a good amount of time thinking about how I would test this before I wrote my first line of code. While the systems testing came later for me, unit testing was done from the very beginning using TDD. I used the docker-compose unit test file to constantly show the me the state of my tests with every file system change. This uses a plugin called nose-watch. I’ll show my development process in a future post.
Installing/Running the Project
I’m not really going to discuss much here, as it is outlined in the readme file within the project itself. If you have not installed Docker before, just bite the bullet and do it. If you are anything like me, just playing with Docker for a little will really change the way you think about deploying software and sharing environments. It really is a game-changer in my opinion.
Once you have Docker and Docker Compose, you should be able to run all the same tests and the application itself just like I do. I’ll also explain the Docker stuff in a future post.
For now, I encourage you to run the unit tests, system test (currently fails but does at least run), and the application itself. If you are familiar with CURL or another way of testing a REST interface, try creating one or two people and getting them. At the time of this writing, there is very little error checking, so you are quite likely to break something if you don’t play nice with it. 🙂 That will get better as I further develop this application.
Let me know if you have any issues running or testing restexample!