REST

REST is a software architectural style that defines a set of constraints to be used for creating web services.

Most explanations of REST give too many details, such as the architectural constraints. To get a glimpse how REST works, this is not necessary. In this article I try to focus on the bare minimum.

HTTP Methods

HTTP methods were designed in 1991, whereas REST was designed in 2000. The following are explanations of HTTP methods in the REST context. The HTTP Methods in REST map to CRUD which is from 1983:

Overview

Naming Conventions

Example

Let's say we have an educational website educate.me. It has lessons:

lesson = {"lesson_id": "int",
          "author_id": "int",
          "content": "blob",
          "expected_age": "int",
          "creation_date": "datetime"}

You need a possibility to:

• list all existing lessons
• get a single lesson
• add a new lesson
• delete a lesson

So your service then has the following URLs:

• GET educate.me/lessons: List all lessons
• GET educate.me/lessons/id/42: List the lesson with ID 42.
• POST educate.me/lessons: Add a new lesson
• DELETE educate.me/lessons/id/42: Delete the lesson with ID 42.

Pimp GET

You should provide filtering, sorting, field selection and pagination for collections.

Pagination

In the example above, GET educate.me/lessons could return something arbitrary big. Instead, it should be limited to something reasonable like 20, 100 or 500 elements. Then the call gets a limit an an offset: GET educate.me/lessons?offset=40&limit=20.

With pagination, the order becomes important. You could sort by default by ID, but maybe you want to offer some sorting options.

Sorting

You can allow sorting options with the syntax GET educate.me/lessons?sort=-creation_date,+lesson_id.

Filtering

Most of the time, clients are not interested in all of the data. They are interested in a part of it.

Some filtering options you might want to consider in the example above:

• ?content=*euclid*
• ?creation_date<=2019-05-30
• ?author_id=42&content=*euclid*

Flask

You can build REST APIs with Flask-RESTPlus:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

#!/usr/bin/env python

"""Simple Flask/Swagger/REST-API example."""

from flask import Flask
from flask_restplus import Resource, Api

app = Flask(__name__)
api = Api(app, doc='/doc')


@api.route('/lessons')
class VersionAPI(Resource):
    def get(self):
        return get_all_lessons()

    def post(self):
        add_posted_lesson()


if __name__ == "__main__":
    app.run(host='0.0.0.0')

See also

• REST Resource Naming Guide