API Reference – User Registration (POST /register)

Index

  1. Overview
  2. Endpoint Definition
  3. Request
    3.1 Headers
    3.2 Body
  4. Responses
  5. Implementation Details
  6. Related Components

Overview

The User Registration endpoint allows clients to create a new user account by providing a unique username and a password. This endpoint is public (no JWT required) and is guarded against duplicate usernames—attempts to register an existing username will result in a 400 Bad Request error.


Endpoint Definition

In app.py, the UserRegister resource is bound to POST /register as follows:

api.add_resource(UserRegister, '/register')

This mapping is initialized when the Flask application starts .


Request

Headers

Header Value Required
Content-Type application/json Yes

Body

Content type: JSON
Clients must supply the following properties:

Field Type Required Description
username string Yes Desired unique username.
password string Yes Secure password for the account.
{
  "username": "johndoe",
  "password": "s3cureP@ss"
}

Responses

Status Code Body Description
201 Created { "message": "User created successfully." } New user record created.
400 Bad Request { "message": "This field cannot be blank." }{ "message": "A user with that username already exists" } Missing fields or duplicate username.
500 Internal Server Error { "message": "An error occurred creating the user." } (not currently thrown by this endpoint, but may occur in extended implementations) Unexpected database or server error.

Example

{
  "title": "User Registration",
  "description": "Creates a new user with a unique username and password.",
  "method": "POST",
  "baseUrl": "http://localhost:5000",
  "endpoint": "/register",
  "headers": [
    {
      "key": "Content-Type",
      "value": "application/json",
      "required": true
    }
  ],
  "bodyType": "json",
  "requestBody": "{\n  \"username\": \"johndoe\",\n  \"password\": \"s3cureP@ss\"\n}",
  "responses": {
    "201": {
      "description": "User created successfully",
      "body": "{\n  \"message\": \"User created successfully.\"\n}"
    },
    "400": {
      "description": "Bad request (missing fields or duplicate username)",
      "body": "{\n  \"message\": \"A user with that username already exists\"\n}"
    }
  }
}

Implementation Details

# resources/user.py
from flask_restful import Resource, reqparse
from models.user import UserModel

class UserRegister(Resource):
    parser = reqparse.RequestParser()
    parser.add_argument(
        'username',
        type=str,
        required=True,
        help="This field cannot be blank."
    )
    parser.add_argument(
        'password',
        type=str,
        required=True,
        help="This field cannot be blank."
    )

    def post(self):
        data = UserRegister.parser.parse_args()
        # Prevent duplicate usernames
        if UserModel.find_by_username(data['username']):
            return {"message": "A user with that username already exists"}, 400

        # Create and persist the new user
        user = UserModel(data['username'], data['password'])
        user.save_to_db()

        return {"message": "User created successfully."}, 201
  • Argument Parsing via Flask-RESTful’s reqparse ensures both username and password are provided and non-empty.
  • Duplicate checks leverage UserModel.find_by_username.
  • Persistence is handled by UserModel.save_to_db().

Component Description
app.py Registers the UserRegister resource and configures JWT, database, and Flask-RESTful.
models/user.py Defines UserModel ORM class mapping to the users table with helper methods.
db.py Initializes SQLAlchemy instance (db = SQLAlchemy()).
security.py Exposes authenticate and identity functions for JWT, utilizing UserModel.
Postman Collection Contains example requests for /register under the “/register” item.

Note: While this endpoint currently does not wrap the database save in a try/except, production-ready implementations should handle potential database errors (e.g., connection issues) and return a 500 Internal Server Error with an appropriate message.