Home / MAD1 / Week 6

Week 6 · APIs and REST: OpenAPI and Flask-RESTful

The one-minute story

By the end of this week you can:

• explain what an API is and name the REST constraints;
• design URLs and choose the right verb and status code for each action;
• write a Flask-RESTful API with Resource, reqparse, marshal_with and abort;
• predict the output of Flask-RESTful code and of curl commands (including which call gives an error);
• document an API in OpenAPI (Swagger) YAML;
• test an API with curl, Postman or Python requests.

Words you need

Idea 1: What an API is and what makes it REST

The server exposes data, and any client can use it: a browser page, an Android app, or a Python script. They agree on URLs, methods and JSON.

API route versus web page route. A web route returns HTML (render_template) and is meant for a person; an API route returns JSON and a status code, and its errors are JSON too (not a styled error page). In one real question the route / returned a Python dict and the answer was that its content type is application/json; and the route returning jsonify({"The list of gadgets": Gadgets}) was a valid API access point: both / and /home can be considered API endpoints.

JSON in 60 seconds

{
  "name": "Asha",
  "age": 27,
  "married": false,
  "phones": ["212-555-1234", 2125551234],
  "address": {"city": "Chennai", "pin": null}
}

Rules: double quotes only on keys and strings, no trailing comma, no comments, values are string, number, true, false, null, object or array. Python mapping: object is dict, array is list, true is True, null is None. In JavaScript, JSON.parse('{"name":"icecream","flavor":"vanilla","type":"cup"}') gives an object, and obj.name + ", " + obj.flavor + ", " + obj.type prints icecream, vanilla, cup: access is by key name, not by position.

Idea 2: Designing the API: URLs, verbs, status codes

Name resources with nouns, in plural, and put the action in the verb, not in the URL.

Not RESTful: GET /api/deleteBook?id=3 or /getAllBooks. (A real exam question used URLs like /delete/val1 and a PUT request: because a route only answered PUT, a plain GET gave "none of these" = 405.)

The CRUD mapping: Create = POST, Read = GET, Update = PUT (or PATCH for a partial update), Delete = DELETE.

Safe and idempotent

Status codes for APIs

Idea 3: Flask-RESTful: Api, Resource and methods

Install: pip install flask-restful. Each Resource is a class; its methods are named get, post, put, delete and are called by the verb. You register it with add_resource(Class, url...).

from flask import Flask, request
from flask_restful import Api, Resource

app = Flask(__name__)
api = Api(app)

students = {1: {"name": "Arjun", "grade": "A"}}

class Student(Resource):
    def get(self, student_id):
        if student_id in students:
            return students[student_id], 200
        return {"message": "Student not found"}, 404

    def put(self, student_id):
        data = request.json
        if student_id in students:
            students[student_id]["grade"] = data.get("grade", students[student_id]["grade"])
            return {"message": "Student record updated", "student": students[student_id]}, 200
        return {"message": "Student not found"}, 404

api.add_resource(Student, "/student/<int:student_id>")

I ran this with the test client. A GET /student/1 returns status 200 and {"name": "Arjun", "grade": "A"}. GET /student/10 returns 404 and {"message": "Student not found"}. PUT /student/1 with JSON {"grade": "A+"} returns 200 and the updated student (grade A+). PUT /student/4 returns 404 because 4 is not in the dictionary: it does not create a record. A URL like /student/abc does not match <int:...> and gives the plain 404 page.

What Flask-RESTful does for you: a returned dict or list becomes JSON; a returned tuple (body, status) sets the status; the response mimetype is application/json. Returning None gives JSON null with status 200.

class UserResource(Resource):
    def get(self):
        return {"status": "GET request"}, 200
    def post(self, user_id):
        return {"status": "POST request", "user_id": user_id}, 201

api.add_resource(UserResource, "/users", "/users/<int:user_id>")

class MyApi(Resource):
    def get(self):  return {"greet": "Hello from GET Api!"}
    def put(self):  return {"greet": "Hello from PUT Api!"}

api.add_resource(MyApi, "/api/get", "/api/put", "/api/post")

Idea 4: Input and output: reqparse, marshal_with, abort

reqparse declares which inputs you expect, converts their type and rejects bad input with a 400.

from flask_restful import reqparse

parser = reqparse.RequestParser()
parser.add_argument("n", type=int, required=True, help="n must be an int")

class MyResponse(Resource):
    def post(self):
        args = parser.parse_args()
        return args                      # a dict-like, so it becomes JSON

api.add_resource(MyResponse, "/")

curl -X POST http://127.0.0.1:5000 -H "Content-Type: application/json" -d "{\"n\":3}"

The reply is {"n": 3} (status 200). With {"n": "x"}, or with no n at all, the reply is 400 and {"message": {"n": "n must be an int"}}. If you send JSON with -d but leave out the Content-Type header, Flask 3 refuses it with a 415 error: so for JSON, curl needs -H "Content-Type: application/json" (as the real question's right answers had). Plain -d "status=active&role=admin" sends form-encoded data (not JSON); with -X PUT it is a PUT in form format, which was the right answer to a real question.

By default reqparse looks in the JSON body and the form. For values from the query string, say so: parser.add_argument("page", type=int, default=1, location="args"). (I found that on Flask 3 a GET with no JSON header and reqparse's default location raises 415, so always set location="args" for GET parameters.)

marshal_with filters and converts your output to the shape in a fields dictionary.

from flask_restful import fields, marshal_with

out_fields = {"Id": fields.Integer, "name": fields.String}

class MyApi(Resource):
    @marshal_with(out_fields)
    def post(self):
        info = parser.parse_args()     # parser has Id, name, email
        return info

curl -X POST ... -d '{"Id":3, "name":"user_1", "email":"user_1@gmail.com"}' returns {"Id": 3, "name": "user_1"}. The email is dropped because it is not in the fields dictionary, and "Id": 3 is a number (fields.Integer), not the string "3". A real question had the same code and its right option was {"Id": 3, "name": "user_1"}. The get method in that class returned a plain dict with the keys Identity, Name, E-mail: no marshal there, so keys are what you wrote.

marshal_with(fields, envelope="book") wraps the output as {"book": {...}}. Fields: fields.Integer, fields.String, fields.Float, fields.Boolean, fields.List(...), fields.Nested(...).

abort with a message. Flask-RESTful has its own abort.

from flask_restful import abort
abort(404, message="Book 99 not found")     # JSON: {"message": "Book 99 not found"}, status 404

from flask import Flask
from flask_restful import Api, Resource, reqparse, fields, marshal_with, marshal, abort

app = Flask(__name__)
api = Api(app)

ITEMS = [{"id": i, "title": f"Book {i}", "price": i * 10, "secret": "x"} for i in range(1, 6)]
book_fields = {"id": fields.Integer, "title": fields.String, "price": fields.Float}

list_parser = reqparse.RequestParser()
list_parser.add_argument("page", type=int, default=1, location="args")
list_parser.add_argument("per_page", type=int, default=2, location="args")
list_parser.add_argument("q", location="args")

new_parser = reqparse.RequestParser()
new_parser.add_argument("title", required=True, help="title is required")
new_parser.add_argument("price", type=int, default=0)

class Books(Resource):
    def get(self):
        a = list_parser.parse_args()
        rows = [b for b in ITEMS if not a["q"] or a["q"] in b["title"]]
        start = (a["page"] - 1) * a["per_page"]
        return {"page": a["page"], "total": len(rows),
                "items": [marshal(b, book_fields) for b in rows[start:start + a["per_page"]]]}

    @marshal_with(book_fields, envelope="book")
    def post(self):
        a = new_parser.parse_args()
        b = {"id": len(ITEMS) + 1, "title": a["title"], "price": a["price"]}
        ITEMS.append(b)
        return b, 201

class Book(Resource):
    @marshal_with(book_fields)
    def get(self, bid):
        for b in ITEMS:
            if b["id"] == bid:
                return b
        abort(404, message=f"Book {bid} not found")

api.add_resource(Books, "/api/v1/books")
api.add_resource(Book, "/api/v1/books/<int:bid>")

salaries = {1: {"name": "Ravi", "basic": 14500}, 2: {"name": "David", "basic": 9500}}

class Salaries(Resource):
    def do_something(self):
        for s in salaries.keys():
            salaries[s]["hra"] = salaries[s]["basic"] * 0.10
    def get(self):
        self.do_something()
        return salaries

api.add_resource(Salaries, "/api/salaries")

Idea 5: Calling and testing an API

curl options to know:

curl http://127.0.0.1:5000/api/v1/books/1
curl -X POST http://127.0.0.1:5000/api/v1/books -H "Content-Type: application/json" -d "{\"title\":\"New\",\"price\":55}"
curl -v http://127.0.0.1:5000/api/v1/books
curl -X DELETE http://127.0.0.1:5000/api/v1/books/1

On Windows cmd, JSON in -d must use double quotes with \" escapes (as in line 2); in Git Bash or Linux you can use single quotes. A real question asked which option shows detailed request/response information for debugging: curl -v (-i just adds the response headers to the output).

From Python with the requests library:

import requests
r = requests.post("http://127.0.0.1:5000/api/v1/books", json={"title": "New", "price": 55})
print(r.status_code)      # 201
print(r.json())           # {'book': {...}}
r = requests.get("http://127.0.0.1:5000/api/v1/books", params={"page": 2})

json= sets the body and the Content-Type header for you. Postman is a point-and-click tool for the same: choose a method, enter the URL, put JSON in the Body tab (raw, JSON), and read status and body.

curl -X PUT http://127.0.0.1:5000/student/1 -H "Content-Type: application/json" -d "{\"grade\":\"B\"}"

Idea 6: Documenting with OpenAPI (Swagger)

Documentation says what endpoints exist, their parameters, body and responses. In the exam, "what describes available endpoints, request parameters and response formats?" has the answer API documentation / API reference; and "OpenAPI Specification is a way to describe interfaces for RESTful APIs" (it is not a programming language, performance tester or auth library).

An OpenAPI file is YAML (or JSON) with these top-level keys:

openapi: 3.0.3
info:
  title: Books API
  version: "1.0"
paths:
  /api/v1/books:
    get:
      summary: List books
      parameters:
        - name: page
          in: query
          schema: {type: integer, default: 1}
      responses:
        "200":
          description: A page of books
          content:
            application/json:
              schema:
                type: array
                items: {$ref: "#/components/schemas/Book"}
    post:
      summary: Create a book
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: "#/components/schemas/NewBook"}
      responses:
        "201": {description: Created}
        "400": {description: Missing or invalid title}
  /api/v1/books/{bid}:
    get:
      summary: Get one book
      parameters:
        - name: bid
          in: path
          required: true
          schema: {type: integer}
      responses:
        "200": {description: The book}
        "404": {description: No such book}
components:
  schemas:
    Book:
      type: object
      properties:
        id: {type: integer}
        title: {type: string}
        price: {type: number}
    NewBook:
      type: object
      required: [title]
      properties:
        title: {type: string}
        price: {type: integer}

Points to notice: path variables are written {bid} (curly braces) here, but <int:bid> in Flask; parameters have in: (query, path, header); response codes are strings; the YAML is indentation-sensitive (use spaces, never tabs). Swagger UI or the Swagger Editor reads this file and gives you a page where you can read and try the API.

Idea 7: Pagination, filtering, versioning and error responses

• Pagination: GET /books?page=2&per_page=10. The server returns one slice and often the total, so clients do not download everything.
• Filtering and sorting: GET /books?author=Asha&sort=price. Filters go in the query string, resource identity goes in the path.
• Versioning: put the version in the path (/api/v1/) or a header, so old clients keep working.
• Error responses: always JSON with the right status, such as {"message": "Book 99 not found"} (404). Flask-RESTful does this for you when you use its abort.
• Cacheable GET: GET responses can be cached; POST responses normally not.

Exam radar

Quick quiz

Viva: say it out loud

Recap

Practise with real exam questions

These come straight from past papers (with the real figures and the official answer key). Open 60 real questions on this week   All Quiz 2 papers