Developing and Testing REST API as an Intermediate | API Documentation - A step by step guide for technical writers

You’ve already built and tested a basic API in the beginner section. Now, it’s time to enhance it with:

URL parameters & query strings to handle dynamic requests
Error handling & validation to prevent bad data
Authentication (API Key) to secure access
Logging API requests for debugging
API documentation using Swagger

By the end of this section, you’ll have a fully functional API with real-world features, making it more powerful and production-ready.

Step 1: Modify Your API to Accept Parameters

Add support for fetching a single user by ID

Modify app.py to allow users to retrieve a specific user by ID:

from flask import Flask, request, jsonify
from flasgger import Swagger

app = Flask(__name__)
Swagger(app)

users = [
    {"id": 1, "name": "Alice", "email": "alice@example.com"},
    {"id": 2, "name": "Bob", "email": "bob@example.com"}
]

@app.route('/users', methods=['GET'])
def get_users():
    """
    Get all users or filter by name
    ---
    parameters:
      - name: name
        in: query
        type: string
        required: false
    responses:
      200:
        description: A list of users
    """
    name_filter = request.args.get('name')
    if name_filter:
        filtered_users = [u for u in users if name_filter.lower() in u["name"].lower()]
        return jsonify(filtered_users)
    return jsonify(users)

@app.route('/users/<int:user_id>', methods=['GET'])
def get_user(user_id):
    """
    Get a user by ID
    ---
    parameters:
      - name: user_id
        in: path
        type: integer
        required: true
    responses:
      200:
        description: A single user object
      404:
        description: User not found
    """
    user = next((u for u in users if u["id"] == user_id), None)
    if user:
        return jsonify(user)
    return jsonify({"error": "User not found"}), 404

if __name__ == '__main__':
    app.run(debug=True)

Visit Swagger UI: http://127.0.0.1:5000/apidocs

Test it in Postman:

GET request: http://127.0.0.1:5000/users/1

Response:

{
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com"
}

Step 2: Implement API Key Authentication

API_KEY = "mysecretapikey"

def check_api_key():
    key = request.headers.get("x-api-key")
    if key != API_KEY:
        return jsonify({"error": "Unauthorized"}), 403

@app.route('/users', methods=['GET'])
def get_users():
    auth = check_api_key()
    if auth:
        return auth
    return jsonify(users)

Visit Swagger UI: http://127.0.0.1:5000/apidocs

Test it in Postman:

Add Header: x-api-key: mysecretapikey
If missing, response:
```
{
  "error": "Unauthorized"
}
```

Step 3: Refactoring Swagger Docs into a Separate File

Instead of writing Swagger docs in every endpoint, let’s separate it:

Using a YAML File for Swagger Docs

Create swagger.yaml:

openapi: 2.0.0
info:
  title: User Info API
  description: API for retrieving user details
  version: 1.0.0
servers:
  - url: http://127.0.0.1:5000
paths:
  /users:
    get:
      summary: Get all users
      parameters:
        - name: name
          in: query
          required: false
          type: string
      responses:
        "200":
          description: A list of users
  /users/{user_id}:
    get:
      summary: Get a user by ID
      parameters:
        - name: user_id
          in: path
          required: true
          type: integer
      responses:
        "200":
          description: User details
        "404":
          description: User not found

Modify app.py to load Swagger YAML:

from flasgger import Swagger
import yaml

app = Flask(__name__)
with open("swagger.yaml", "r") as f:
    swagger_template = yaml.safe_load(f)
Swagger(app, template=swagger_template)

Now, your API documentation is clean, structured, and easy to maintain! 🚀

What’s Next?

Congrats! You now:

Understand how to handle dynamic API requests
Implement authentication with API keys
Use Swagger to document APIs
Test APIs using Postman

Let’s move to expert level

Found value in the course? Your support fuels my work!

Course completed

65%

Have an issue? Please provide specific feedback by reporting an issue.