Developing and Testing a REST API for Beginners

Learn how to build, document, and test your own REST API using Python Flask and Postman. This step-by-step tutorial covers creating endpoints, implementing CRUD operations, and documenting with Swagger.

Table of Contents

You’ve documented APIs, but now it’s time to take a hands-on approach—let’s build, document, and test our own API step by step!

Learning by Building

Creating your own API is one of the best ways to truly understand how APIs work. In this guide, you'll build a simple but functional REST API that implements all the concepts you've learned about in the documentation chapters.

What You’ll Learn in This Tutorial

By the end of this hands-on guide, you’ll be able to:

• Set up a development environment for API creation
• Build a REST API with Python and Flask
• Implement CRUD operations (Create, Read, Update, Delete)
• Document your API using Swagger/OpenAPI
• Test endpoints using Postman and cURL
• Organize API documentation for better maintainability

Let’s dive in and start building!

Setting Up Your Development Environment

Before we start coding, you’ll need to prepare your development environment with the necessary tools.

Tool	Purpose	Installation Command
Python	Programming language for our API	Download from Python.org
Flask	Web framework for creating APIs	pip install flask
Flasgger	Swagger integration for Flask	pip install flasgger
Postman	API testing tool	Download from Postman.com

Installation Steps

1. Install Python from the Python Official Website
2. Install Flask and Flasgger using pip:

pip install flask flasgger

1. Verify your installations:

python --version
pip show flask flasgger

Tip

Consider using a virtual environment to keep your project dependencies isolated. Create one with python -m venv env and activate it before installing packages.

Building a Basic Flask API

Let’s start with a simple Hello World API to make sure everything is working correctly.

Step 1: Create Your First API Endpoint

Create a file named app.py and add the following code:

from flask import Flask, jsonify
from flasgger import Swagger

app = Flask(__name__)
Swagger(app)

@app.route('/')
def home():
    """
    Welcome Endpoint
    ---
    responses:
      200:
        description: Welcome Message
    """
    return jsonify({"message": "Hello, API World!"})

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

Step 2: Run Your API

Save the file and run it with Python:

python app.py

You should see output similar to:

 * Serving Flask app 'app' (lazy loading)
 * Environment: production
   WARNING: This is a development server. Do not use it in a production deployment.
 * Debug mode: on
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

Step 3: Access Your API

Try these two ways to access your new API:

1. View API Documentation:
   • Open your browser and navigate to http://127.0.0.1:5000/apidocs
   • You’ll see the Swagger UI showing your API documentation
2. Test with Postman:
   • Open Postman
   • Create a new GET request to http://127.0.0.1:5000/
   • Send the request
   • You should receive a response: {"message": "Hello, API World!"}

Response (200 OK)

{
  "message": "Hello, API World!"
}

Creating CRUD Endpoints

Now that we have our basic API working, let’s implement the four standard operations (CRUD) for a user management system:

• Create: Adding new users
• Read: Retrieving user data
• Update: Modifying existing users
• Delete: Removing users

GET Endpoint (Read)

Let’s add a GET endpoint to retrieve a list of users:

@app.route('/users', methods=['GET'])
def get_users():
    """
    Get all users
    ---
    responses:
      200:
        description: A list of users
    """
    users = [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
    return jsonify(users)

Add this code to your app.py file after the home route but before the if __name__ == '__main__' line.

Test it with Postman:

• Send a GET request to http://127.0.0.1:5000/users
• You should receive a JSON array with two users

Response (200 OK)

[
  {
    "id": 1,
    "name": "Alice"
  },
  {
    "id": 2,
    "name": "Bob"
  }
]

POST Endpoint (Create)

Now let’s add a POST endpoint to create new users:

from flask import request

@app.route('/users', methods=['POST'])
def add_user():
    """
    Add a new user
    ---
    parameters:
      - name: body
        in: body
        required: true
        schema:
          type: object
          properties:
            name:
              type: string
    responses:
      201:
        description: User added successfully
    """
    data = request.get_json()
    return jsonify({"message": "User added!", "user": data}), 201

Test it with Postman:

• Create a POST request to http://127.0.0.1:5000/users
• Set the Content-Type header to application/json
• Add this JSON to the request body:

  {
    "name": "Charlie"
  }
  

• Send the request
• You should receive a 201 Created response

Response (201 Created)

{
  "message": "User added!",
  "user": {
    "name": "Charlie"
  }
}

PUT Endpoint (Update)

Let’s add a PUT endpoint to update existing users:

@app.route('/users/<int:user_id>', methods=['PUT'])
def update_user(user_id):
    """
    Update a user
    ---
    parameters:
      - name: user_id
        in: path
        required: true
        type: integer
      - name: body
        in: body
        required: true
        schema:
          type: object
          properties:
            name:
              type: string
    responses:
      200:
        description: User updated successfully
    """
    data = request.get_json()
    return jsonify({"message": "User updated!", "user_id": user_id, "new_data": data})

Test it with Postman:

• Create a PUT request to http://127.0.0.1:5000/users/1
• Set the Content-Type header to application/json
• Add this JSON to the request body:

  {
    "name": "Updated Name"
  }
  

• Send the request
• You should receive a success response

Response (200 OK)

{
  "message": "User updated!",
  "user_id": 1,
  "new_data": {
    "name": "Updated Name"
  }
}

DELETE Endpoint (Delete)

Finally, let’s add a DELETE endpoint to remove users:

@app.route('/users/<int:user_id>', methods=['DELETE'])
def delete_user(user_id):
    """
    Delete a user
    ---
    parameters:
      - name: user_id
        in: path
        required: true
        type: integer
    responses:
      200:
        description: User deleted successfully
    """
    return jsonify({"message": "User deleted!", "user_id": user_id})

Test it with Postman:

• Create a DELETE request to http://127.0.0.1:5000/users/1
• Send the request
• You should receive a success response

Response (200 OK)

{
  "message": "User deleted!",
  "user_id": 1
}

API Documentation with Swagger

The docstrings with triple quotes (""") you’ve been adding are not just comments—they’re actually part of your API documentation using Swagger. Let’s improve this by organizing our Swagger docs.

Option 1: Using a Separate Python File

Keep your API code clean by moving documentation to a separate file:

1. Create a new file swagger_config.py:

swagger_template = {
    "swagger": "2.0",
    "info": {
        "title": "User API",
        "description": "API for managing users",
        "version": "1.0.0"
    },
    "paths": {
        "/users": {
            "get": {
                "summary": "Get all users",
                "responses": {
                    "200": {
                        "description": "A list of users"
                    }
                }
            },
            "post": {
                "summary": "Add a new user",
                "parameters": [
                    {
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "type": "object",
                            "properties": {
                                "name": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "User added successfully"
                    }
                }
            }
        },
        "/users/{user_id}": {
            "put": {
                "summary": "Update a user",
                "parameters": [
                    {
                        "name": "user_id",
                        "in": "path",
                        "required": true,
                        "type": "integer"
                    },
                    {
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "type": "object",
                            "properties": {
                                "name": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "User updated successfully"
                    }
                }
            },
            "delete": {
                "summary": "Delete a user",
                "parameters": [
                    {
                        "name": "user_id",
                        "in": "path",
                        "required": true,
                        "type": "integer"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "User deleted successfully"
                    }
                }
            }
        }
    }
}

1. Update your app.py file to use this configuration:

from swagger_config import swagger_template
Swagger(app, template=swagger_template)

Option 2: Using a YAML File

For even better organization, use a YAML file for documentation:

1. Create a new file 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
      responses:
        "200":
          description: Successful response with user details
    post:
      summary: Add a new user
      parameters:
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              name:
                type: string
      responses:
        "201":
          description: User added successfully
  /users/{user_id}:
    put:
      summary: Update a user
      parameters:
        - name: user_id
          in: path
          required: true
          type: integer
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              name:
                type: string
      responses:
        "200":
          description: User updated successfully
    delete:
      summary: Delete a user
      parameters:
        - name: user_id
          in: path
          required: true
          type: integer
      responses:
        "200":
          description: User deleted successfully

1. Update your app.py file to load the YAML file:

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)

API Documentation Best Practices

Best Practice	Implementation	Benefit
Separate documentation from code	Use external YAML or Python files	Easier to maintain and update without touching API code
Include request examples	Add example values in schema definitions	Helps developers understand expected formats
Document all parameters	Include parameter descriptions and requirements	Reduces confusion and support requests
Use clear response examples	Include sample responses for each endpoint	Sets expectations for API consumers
Version your API docs	Include version numbers in documentation	Enables backward compatibility tracking

Next Steps in API Development

Congratulations! You’ve successfully:

• Built a functional REST API with Flask
• Implemented all four CRUD operations
• Added Swagger documentation for your API
• Tested your endpoints with Postman
• Learned how to organize API documentation for better maintainability

Where to Go From Here

To build on what you’ve learned, consider these next steps:

1. Add persistent storage with a database like SQLite or PostgreSQL
2. Implement authentication with JWT or API keys
3. Add input validation to ensure data integrity
4. Implement pagination for handling large collections
5. Create more complex endpoints that relate different resources
6. Deploy your API to a cloud platform like Heroku or AWS

Key Takeaways

• Building an API requires understanding both the server-side implementation and client-side consumption
• Flask provides a lightweight framework for creating REST APIs in Python
• CRUD operations (Create, Read, Update, Delete) form the foundation of most APIs
• Swagger/OpenAPI documentation makes your API easier to understand and use
• Separating documentation from code improves maintainability
• Testing with tools like Postman is essential for ensuring API functionality

What’s Next?

Ready for the next challenge? In the Intermediate API Development chapter, we’ll explore more advanced concepts like database integration, authentication, and performance optimization.

API Development Resources

Expand your API development skills with these resources.

External Resources

• Flask Documentation
• Swagger/OpenAPI Specification
• REST API Design Best Practices

Tools & APIs

• Postman API Platform
• Swagger Editor
• HTTPie - Command Line HTTP Client

Previous: Expert REST API Exercises Next: Intermediate API Development

Start your learning journey!

Course Progress 0%

0 of 0 pages completed

Found value in the course?

Your support fuels my work!

Have an issue?

Help improve the course by reporting an issue