What is a REST API?
It stands for REpresentational State Transfer. This means each unique URL is a representation of an object. It’s one of the web services that allows for data transport, other notable alternative is SOAP. It offers CRUD (Create, Read, Update, Delete) object operations via POST, PUT, GET and DELETE.
Why go for it?
It’s used to build web service APIs that allow for decoupling of the user interface from the back-end logic. The less business logic you have in the front-end, the better and more maintainable the code is. Once the communication interface is agreed with the service, the UI code shouldn’t know anything of the implementation of the back-end. Each request is stateless and independent of the previous one. It’s standardized and well established in any modern browser. It’s extremely lighweight and stable compared to creating proprietary communication protocols from scratch and supporting them. It offers human readable results and is flexible in return formats – JSON or XML. Last, but not least – very fast and easy to develop, implying maintainability.
In this post we’ll go through the setup, creation & testing of a RESTful service with Flask.
Download and install Python 3 (preferably 64bit) from Python Software Foundation. Then we need to install Flask using PIP, append –user if you are don’t have admin rights.
The second install is an extension that offers syntactic sugar when it comes to parsing received requests, handling nicely null values and other goodies. All listed here. Going through the example below, it will make more sense.
We start with a basic skeleton
Then we provide some dummy users data:
We want to build support for adding, updating and removing a user and also to fetch all users. So we’ll implement a class that supports these methods. Each return is a tuple, where you pass the return object alongside a return code.
The standard return codes are :
1xx – Info, 2xx – Success, 3xx – Redirect, 4xx – Client Error, 5xx – Server Error.
This is where the famous 404 Page Not Found comes from, for the non-technical readers.
Then we implement the methods:
Lastly, we want to get all users from the list. As we are good citizens we’ll create a new class that will deal with Bulk operations and add this one too. The /user/ branch of your service always expects a name argument. You can skip the age, when registering a user, but a name is always needed, thus you need to pass <string:name>, as shown below:
Notice we don’t pass the string requirement for /users/, as we want an empty request, because of this, our methods’ signatures only take self.
Save the file as service.py and run python service.py and should get a console output like:
Restarting with stat
* Debugger is active!
* Debugger PIN: 206-008-437
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
Download and install Postman from https://www.getpostman.com/, you can skip the registration on the first opening of the application and paste the generated URL from the console in the middle of the tool and append /user/John to the url and select the type to be POST on the left and click Send. As per the screenshot:
to pass the age append ?age=55 You can try http://127.0.0.1:5000/users to get the entire list of users. Don’t forget to switch the request to GET on the left.
Should your REST API have a schema?
Yes, for documentation. Have a look at SoundCloud’s Reference API.
Clean, Succinct and self-explanatory. Always document!
A paradigm like:
http://host/v1/users vs http://host/v2/users
has benefits and drawbacks, here’s an extensive blog post that focuses on this.