• Martin Thoma
  • Home
  • Categories
  • Tags
  • Archives
  • Support me

REST

Contents

  • HTTP Methods
  • Overview
  • Naming Conventions
  • Example
  • Pimp GET
    • Pagination
    • Sorting
    • Filtering
  • Flask
  • See also

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:

HTTP CRUD SQL REST meaning
POST CREATE INSERT Create a new resrouce, but server decides on URI / ID.
PUT Like POST, but the server creates the URI / ID.
GET READ SELECT Retrieve one or multiple resources. This MUST NOT change an resource!
PUT UPDATE UPDATE Like POST, but the server creates the URI / ID.
PATCH Change a resource
DELETE DELETE DELETE Delete one or multiple resources.

Overview

HTTP method Response Status Code Response Body (JSON or Empty) Meaning
GET 200 The resource Found resource
404 Empty or error description Resource not found
POST 201 The created resource Resource created
400 Empty or error description Invalid resource
409 Empty or error description Resource already exists
PUT 201 Empty? Description? Resource? Update resource
PATCH 200 Empty? Description? Resource? Update resource
404 Empty or error description Resource not found
DELETE 200 Empty Resource deleted
404 Empty Resource not found

Naming Conventions

# Rule Wrong Right
1 Only Nouns getLessons lessons
2 Only Plural forms lesson lessons
3 Use hyphens, not underscores room_number room-number
4 Only lower-case letters Lessons lessons

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-RESTX:

#!/usr/bin/env python

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

from flask import Flask
from flask_restx 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

Published

Mai 18, 2019
by Martin Thoma

Category

The Web

Tags

  • API 2
  • Architecture 5
  • Design 8
  • Flask 6
  • Web 2

Contact

  • Martin Thoma - A blog about Code, the Web and Cyberculture
  • E-mail subscription
  • RSS-Feed
  • Privacy/Datenschutzerklärung
  • Impressum
  • Powered by Pelican. Theme: Elegant by Talha Mansoor