Home>Programming related>Python
Download

Bulletin board

Creating a minimum viable bulletin board REST API for educational purposes.

Functional

  • Getting lists of all tags, posts and users

  • Search in lists

  • User registration

  • A registered user can:

    • Add new posts

    • Comment on existing posts

    • Delete and edit your posts and comments

Requirements

  • PHP 8.1+

  • Laravel 10

  • Composer

  • MySQL

Documentation

Authentication

POST /api/v1/auth/register Register
Body
Name Type Data type Description
name required string Name
nickname required string Human-readable identifier
email required string Email address
password required string Password
password_confirmed required string Password confirmation
Success Response
HTTP Code: 201 CREATED 
{
    "access_token",
    "token_type": "Bearer"
}
POST /api/v1/auth/login Login
Body
Name Type Data type Description
email required string Email address
password required string Password
Success Response
HTTP Code: 200 OK 
{
    "access_token",
    "token_type":"Bearer"
}
POST /api/v1/auth/logout Logout
Headers
Key Value
Authorization Bearer {token}
Success Response
HTTP Code: 204 NO CONTENT

Profile

GET /api/v1/profile Get authenticated user profile
Headers
Key Value
Authorization Bearer {token}
Response
HTTP Code: 200 OK 
{
    "data": {
        "user_id",
        "name",
        "nickname",
        "email",
        "created_at",
        "updated_at",
        "posts_count",
        "comments_count"
    }
}
GET /api/v1/profile/posts Get the profile and posts of an authenticated user
Headers
Key Value
Authorization Bearer {token}
Params
Name Type Data type Description
per_page optional int Number of posts per page
page optional int Page number
Response
HTTP Code: 200 OK 
{
    "data": [
        {
            "post_id",
            "title",
            "price",
            "description",
            "created_at",
            "updated_at",
            "user_id",
            "user_nickname",
            "tags": [
                {
                    "tag_id",
                    "name",
                    "slug",
                },
                ...
            ],
            "comments_count"
        }
    ],
    "links": {...},
    "meta": {...},
    "user": {
        "user_id",
        "name",
        "nickname",
        "email",
        "created_at",
        "updated_at"
    }
}
GET /api/v1/profile/comments Get the profile and comments of an authenticated user
Headers
Key Value
Authorization Bearer {token}
Params
Name Type Data type Description
per_page optional int Number of comments per page
page optional int Page number
Success Response
HTTP Code: 200 OK 
{
    "data": [
        {
            "comment_id",
            "body",
            "created_at":,
            "updated_at",
            "post_id",
            "user_id",
            "user_nickname"
        },
        ...
    ],
    "links": {...},
    "meta": {...},
    "user": {
        "user_id",
        "name",
        "nickname",
        "email",
        "created_at",
        "updated_at"
    }
}

Users

GET /api/v1/users Get all users
Params
Name Type Data type Description
q optional string Search query
per_page optional int Number of users per page
page optional int Page number
Success Response
HTTP Code: 200 OK 
{
    "data": [
        {
            "user_id",
            "name",
            "nickname",
            "email",
            "created_at",
            "updated_at",
            "posts_count",
            "comments_count"
        },
        ...
    ],
    "links": {...},
    "meta": {...}
}
GET /api/v1/users/{nickname} Get user
Success Response
HTTP Code: 200 OK 
{
    "data": {
        "user_id",
        "name",
        "nickname",
        "email",
        "created_at",
        "updated_at",
        "posts_count",
        "comments_count"
    }
}
GET /api/v1/users/{nickname}/posts Get the user and his posts
Params
Name Type Data type Description
per_page optional int Number of posts per page
page optional int Page number
Success Response
HTTP Code: 200 OK 
{
    "data": [
        {
            "post_id",
            "title",
            "price",
            "description",
            "created_at",
            "updated_at",
            "user_id",
            "user_nickname",
            "tags": [
                {
                    "tag_id",
                    "name",
                    "slug"
                },
                ...
            ],
            "comments_count"
        },
        ...
    ],
    "links": {...},
    "meta": {...},
    "user": {
        "user_id",
        "name",
        "nickname",
        "email",
        "created_at",
        "updated_at"
    }
}
GET /api/v1/users/{nickname}/comments Get the user and his comments
Params
Name Type Data type Description
per_page optional int Number of comments per page
page optional int Page number
Success Response
HTTP Code: 200 OK 
{
    "data": [
        {
            "comment_id",
            "body",
            "created_at":,
            "updated_at",
            "post_id",
            "user_id",
            "user_nickname"
        },
        ...
    ],
    "links": {...},
    "meta": {...},
    "user": {
        "user_id",
        "name",
        "nickname",
        "email",
        "created_at",
        "updated_at"
    }
}

Tags

GET /api/v1/tags Get all tags
Params
Name Type Data type Description
q optional string Search query
Success Response
HTTP Code: 200 OK 
{
    "data": [
        {
            "tag_id",
            "name",
            "slug",
            "post_count"
        },
        ...
    ]
}
GET /api/v1/tags/{slug} Get a tag and its posts
Params
Name Type Data type Description
per_page optional int Number of posts per page
page optional int Page number
Success Response
HTTP Code: 200 OK 
{
    "data": [
        {
            "post_id",
            "title",
            "price",
            "description",
            "created_at",
            "updated_at",
            "user_id",
            "user_nickname"
        },
    ],
    "links": {...},
    "meta": {...},
    "tag": {
        "tag_id",
        "name",
        "slug"
    }
}

Posts

GET /api/v1/posts Get all posts
Params
Name Type Data type Description
q optional string Search query
per_page optional int Number of posts per page
page optional int Page number
Success Response
HTTP Code: 200 OK 
{
    "data": [
        {
            "post_id,
            "title",
            "price",
            "description",
            "created_at",
            "updated_at",
            "user_id",
            "user_nickname",
            "tags": [
                {
                    "tag_id",
                    "name",
                    "slug"
                },
                ...
            ],
            "comments_count"
        },
        ...
    ],
    "links": {...},
    "meta": {...}
}
GET /api/v1/posts/{id} Get a post and its comments
Params
Name Type Data type Description
per_page optional int Number of comments per page
page optional int Page number
Success Response
HTTP Code: 200 OK 
{
    "data": [
        {
            "comment_id",
            "body",
            "created_at",
            "updated_at",
            "post_id",
            "user_id",
            "user_nickname"
        },
        ...
    ],
    "links": {...},
    "meta": {...},
    "post": {
        "post_id",
        "title",
        "price",
        "description",
        "created_at",
        "updated_at",
        "user_id",
        "user_nickname",
        "tags": [
            {
                "tag_id",
                "name",
                "slug"
            },
            ...
        ]
    }
}
POST /api/v1/posts Add new post
Headers
Key Value
Authorization Bearer {token}
Body
Name Type Data type Description
title optional string Title
price optional float Price
description optional string Description
tags[id] optional array[int] Array of tag IDs
Success Response
HTTP Code: 201 CREATED 
{
    "data": {
        "post_id",
        "title",
        "price",
        "description",
        "created_at",
        "updated_at",
        "user_id",
        "user_nickname",
        "tags": [
            {
                "tag_id",
                "name",
                "slug"
            },
            ...
        ]
    },
}
PUT /api/v1/posts/{id} Edit post
Headers
Key Value
Authorization Bearer {token}
Body
Name Type Data type Description
title optional string Title
price optional float Price
description optional string Description
tags[id] optional array[int] Array of tag IDs
Success Response
HTTP Code: 200 OK 
{
    "data": {
        "post_id",
        "title",
        "price",
        "description",
        "created_at",
        "updated_at",
        "user_id",
        "user_nickname",
        "tags": [
            {
                "tag_id",
                "name",
                "slug"
            },
            ...
        ]
    },
}
DELETE /api/v1/posts/{id} Delete a post
Headers
Key Value
Authorization Bearer {token}
Success Response
HTTP Code: 204 NO CONTENT

Comments

POST /api/v1/posts/{id}/comments Add a new comment to a post
Headers
Key Value
Authorization Bearer {token}
Body
Name Type Data type Description
body required string Comment text
Success Response
HTTP Code: 201 CREATED 
{
    "data": {
        "comment_id",
        "body",
        "created_at",
        "updated_at",
        "post_id",
        "user_id",
        "user_nickname",
    },
}
PUT /api/v1/comments/{id} Edit comment
Headers
Key Value
Authorization Bearer {token}
Body
Name Type Data type Description
body required string Comment text
Success Response
HTTP Code: 200 OK 
{
    "data": {
        "comment_id",
        "body",
        "created_at",
        "updated_at",
        "post_id",
        "user_id",
        "user_nickname",
    }
}
DELETE /api/v1/comments/{id} Delete a comment
Headers
Key Value
Authorization Bearer {token}
Success Response
HTTP Code: 204 NO CONTENT

Launch

  1. Clone this repository and go to your project folder:

 git clone https://github.com/AllaAverina/bulletin-board-APIcd bulletin-board-API

  1. Install dependencies:

 composer install

  1. Start MySQL, change the parameters for connecting to the database in the .env.example file and run:

 copy .env.example .env

  1. Run the command to run the migrations:

 php artisan migrate

Or if you want to populate the database with dummy data:

 php artisan migrate --seed

  1. Start the web server:

 php artisan serve

  1. Open in your browser, for example, http://localhost:8000/api/v1/posts

Running tests

Create a new database for testing, change the parameters to connect to it in the .env.testing file and run:

 php artisan test

Running in Docker

  1. Clone this repository and go to your project folder:

 git clone https://github.com/AllaAverina/bulletin-board-APIcd bulletin-board-API

  1. Install dependencies:

 docker run --rm
     -u "$(id -u):$(id -g)"
     -v "$(pwd):/var/www/html"
     -w /var/www/html
     laravelsail/php82-composer:latest
     composer install --ignore-platform-reqs

  1. Create a .env file:

 cp.env.docker.examlpe.env

  1. Create a shell alias and run sail:

 alias sail='[ -f sail ] && sh sail || sh vendor/bin/sail'sail up -d

  1. Run the command to run the migrations:

 sail artisan migrate

Or if you want to populate the database with dummy data:

 sail artisan migrate --seed

  1. Open in a browser, for example, http://localhost/api/v1/posts

  2. To stop containers use:

 sail stop

Running tests in Docker

  1. Set up the .env.testing file:

 cp .env.docker.testing .env.testing

  1. Run the tests:

 sail artisan test
Expand
Additional Information
Related Applications
Recommended for You
Related Information All