Spitfire Superadmin API Documentation

Welcome to the official documentation for the Spitfire Superadmin API. This RESTful API is designed to provide administrators with comprehensive tools for managing shops, products, vendors, and ensuring the health of the system. Please refer to this documentation to understand the available endpoints, their functionality, and how to use them effectively.

1. Introduction

The Spitfire Superadmin API is a powerful system administration tool designed to provide administrators with complete control over shops, products, and vendors. It enables you to ensure the health and stability of the system. This API is essential for managing an e-commerce platform effectively.

2. Features

All API endpoints are meant for the superadmin and therefore require a verification token to access. Includes endpoints for product and shop management.

3. Technologies Used

Utilizes technologies like Python, Flask, SQLAlchemy, and more.

4. Getting Started

4.1 Prerequisites

4.1.1 Clone The Repository

To get started with the local development environment, clone the repository:

$ git clone https://github.com/hngx-org/spitfire-super-admin-one.git
$ cd super_admin_1

4.1.2 Install Dependencies

You can set up the environment using either venv or pipenv. Here are instructions for both:

Using venv:

# create Virtual Environment
$ python3 -m venv venv

# Activate Virtual Env
$ source venv/bin/activate

# Install Dependencies
$ pip install -r requirements.txt

Using pipenv:

$ pip install pipenv

# create virtuel environment
$ pipenv --python 3.10

# Activate virtual env
$ pipenv shell

# install dependencies in requirements.txt or pipfile
$ pipenv install

4.1.3 Configure Environment Variables

Make sure to set the following environment variables:

SECRET_KEY: [Your Secret Key]
SQLALCHEMY_DATABASE_URI: [Your Database URI]

4.1.4 Usage

$ python3 run.py

5. API Endpoints

Endpoint : /api/admin

5.1 Shop

Endpoint : /shop

The Shop endpoints allow administrators to manage shops and vendors effectively.

5.1.1 Get Information from the Shop Endpoint

GET: /endpoint
- Summary: Get information from the shop endpoint
- Description: This endpoint retrieves information from the shop endpoint. The user ID is automatically provided by the authorization logic.
- Responses:
  - 200: Successful response
    - Message: "This is the shop endpoint for user ID: <user_id>"
  - 401: Unauthorized - Invalid or missing authentication token
  - 403: Forbidden - User does not have permission to access the resource

5.1.2 Get information related to all shops

GET: /all
- Summary: Get information related to all shops
- Description: This endpoint retrieves information related to all shops in the system. Requires admin authentication.
- Responses:
  - 200: Successful response
    - Message: "All shops request successful"
    - Data: Array of shop details
  - 401: Unauthorized - Invalid or missing authentication token
  - 403: Forbidden - User does not have permission to access the resource
  - 500: Internal Server Error

5.1.3 Get information related to a specific shop

GET: /{shop_id}
- Summary: Get information related to a specific shop
- Description: This endpoint retrieves information related to a specific shop identified by the provided shop ID. Requires admin authentication.
- Parameters:
  - shop_id (Path Parameter, Required): Unique identifier for the shop
- Responses:
  - 200: Successful response
    - Message: "Shop request successful"
    - Data: Shop details
  - 401: Unauthorized - Invalid or missing authentication token
  - 403: Forbidden - User does not have permission to access the resource
  - 404: Not Found - Shop with the given ID not found
  - 500: Internal Server Error

5.1.4 Ban a vendor/shop by ID

PUT: /ban_vendor/{vendor_id}
- Summary: Ban a vendor/shop by ID
- Parameters:
  - vendor_id (Path Parameter, Required): Unique identifier for the vendor
  - reason (Request Body, Required): Ban reason
- Responses:
  - 201: Vendor banned successfully
    - Message: "Vendor account banned temporarily."
    - Vendor details
    - Reason
  - 400: Bad request - Vendor is already banned or missing reason
  - 404: Vendor not found
  - 409: Conflict - Vendor is already banned
  - 500: Internal Server Error

5.1.5 Get a list of all temporarily banned vendors

GET: /banned_vendors
- Summary: Get a list of all temporarily banned vendors
- Responses:
  - 200: Successful response
    - Message: "Banned vendors retrieved successfully."
    - Banned vendors

5.1.6 Unban a vendor by ID

PUT: /unban_vendor/{vendor_id}
- Summary:
- Parameters:
  - vendor_id (Path Parameter, Required): Unique identifier for the vendor
- Responses:
  - 200: Vendor unbanned successfully
    - Status: "Success"
    - Message: "Vendor unbanned successfully."
    - Vendor details
  - 404: Vendor not found
  - 400: Vendor's shop is not active
  - 500: Internal Server Error

5.1.7 Restore a temporarily deleted shop by ID

PATCH: /restore_shop/{shop_id}
- Summary: Restore a temporarily deleted shop by ID
- Parameters:
  - shop_id (Path Parameter, Required): Unique identifier for the shop
- Responses:
  - 200: Shop restored successfully
    - Message: "Shop restored successfully"
  - 404: Invalid Shop
  - 400: Invalid JSON Data

5.1.8 Temporarily delete a shop and its associated products

PATCH: /delete_shop/{shop_id}
- Summary: Temporarily delete a shop and its associated products
- Parameters:
  - shop_id (Path Parameter, Required): Unique identifier for the shop
- Responses:
  - 204: Shop temporarily deleted
  - 404: Invalid Shop
  - 500: Internal Server Error

5.1.9 Permanently delete a shop and its associated products

DELETE: /permanent_delete_shop/{shop_id}
- Summary: Permanently delete a shop and its associated products
- Parameters:
  - shop_id (Path Parameter, Required): Unique identifier for the shop
- Responses:
  - 204: Shop permanently deleted
  - 404: Invalid Shop
  - 500: Internal Server Error

5.1.10 Retrieve temporarily deleted vendors

Get: /temporarily_deleted_vendors -Summary: Retrieve temporarily deleted vendors -Responses:
- 200 : Successful response
  - Message: "Temporarily deleted vendors retrieved successfully"
- 500 : Internal Server Error

5.1.11 Retrieve details of a temporarily deleted vendor

Get: /temporarily_deleted_vendor/{vendor_id} -Summary: Retrieve details of a temporarily deleted vendor
- Parameters:
  - vendor_id (Path Parameter, Required): Unique identifier for the vendor
- Responses:
  - 200: Temporarily deleted vendor details retrieved successfully
  - 404: Temporarily deleted vendor not found
  - 500: Internal Server Error

5.1.12 Get all sanctioned shops

Get: /sanctioned -Summary: Returns a list of all sanctioned shops -Responses:
- 200: Sanctioned shops retrieved successfully
- 500: Internal Server Error

5.2 Product

Endpoint: /product

5.2.1 Get information related to all products

GET: /all
- Summary: Get information related to all products
- Description: Returns a list of all products in the system.
- Responses:
  - 200: Successful response
    - Message: "All products retrieved successfully."
    - Data: List of products
  - 500: Internal Server Error

5.2.2 Get information related to a product

GET: /{product_id}
- Summary: Get information related to a product
- Description: Returns details of a specific product.
- Parameters:
  - product_id (Path Parameter, Required): Unique identifier for the product
- Responses:
  - 200: Successful response
    - Message: "Product details retrieved successfully."
    - Data: Product details
  - 404: Product not found
  - 500: Internal Server Error

5.2.3 Sanction a product

PATCH: /sanction/{product_id}
- Summary: Sanction a product by setting its status to 'suspended'
- Parameters:
  - product_id (Path Parameter, Required): Unique identifier for the product
- Responses:
  - 200: Product sanctioned successfully
    - Message: "Product sanctioned successfully."
    - Product details
  - 404: Product not found
  - 409: Conflict - Product is already sanctioned
  - 500: Internal Server Error

5.2.4 Get product statistics

GET: /product_statistics
- Summary: Get statistics about products
- Responses:
  - 200: Product statistics retrieved successfully
    - TotalProducts: Total number of products
    - SanctionedProducts: Total number of sanctioned products
    - DeletedProducts: Total number of deleted products
  - 400: Bad request
  - 500: Internal Server Error

5.2.5 Temporarily delete a product by ID

PATCH: /delete_product/{id}
- Summary: Temporarily delete a product by ID
- Parameters:
  - id (Path Parameter, Required): Unique identifier for the product
- Responses:
  - 204: Product temporarily deleted
  - 404: Invalid Product
  - 409 : Action already carried out on this Product
  - 500: Internal Server Error

5.2.6 Permanently delete a product by ID

DELETE: /permanent_delete_product/{id}
- Summary: Permanently delete a product by ID
- Parameters:
  - id (Path Parameter, Required): Unique identifier for the product
- Responses:
  - 204: Product permanently deleted
  - 404: Invalid Product
  - 500: Internal Server Error

5.2.7 Restore a temporarily deleted product

PATCH: /restore_product/{product_id}
- Summary: Restore a temporarily deleted product by id
- Parameters: -id (Path Parameter, Required): Unique identifier for the product
- Responses:
  - 200: Product restored successfully
  - 404: Invalid Product

5.2.8 Approve a product

PATCH: /approve_product/{product_id}
- Summary: Approve a product by changing the admin status
- Parameters: -id (Path Parameter, Required): Unique identifier for the product
- Responses:
  - 201: Product approved successfully
  - 404: Product not found
  - 409: Conflict. Action already carried out on this Product
  - 500: Internal Server Error

5.2.9 Retrieve temporarily deleted products

GET: /temporarily_deleted_products
Responses:
- 200: Successful response
- 500: Internal Server Error

5.2.10 Download product logs

GET: /download/log
Responses:
- 200: Successful response
- 204: No log entry exists

5.3 Health

Endpoint: /health

5.3.1 Check the availability of specified API endpoints

GET: /
Response:
- 200: Successful health check
- 500: Internal Server Error

5.3.2 Retrieve the last health check log entry

GET: /last_check
Summary:
- 200: Successful retrieval of the last health check log entry
- 404: No health check logs available
- 500: Internal Server Error

5.4 Test

Endpoint: /test

5.4.1 Create a new user

POST: /user/create
Response:
- 201: User created successfully
- 400: Bad request - Invalid input data

5.4.2 Get all users

GET: /user
Response:
- 200: Successful response

5.4.3 Delete a user by ID

DELETE: /user/{user_id}
Parameters: -user_id (Path Parameter, Required): Unique identifier for the user
Response:
- 200: User deleted successfully
- 404: User not found

5.4.4 Cretae a new shop for a user

POST: /user/{user_id}/shop
Parameters: -user_id (Path Parameter, Required): Unique identifier for the user
Response:
- 201: Shop created successfully
- 400: Bad request - Invalid input data

5.4.5 Get all shops

GET: /
Response:
- 200: Successful response

5.4.6 Get a specific shop by ID

GET: /{shop_id}
Parameters: -shop_id (Path Parameter, Required): Unique identifier for the shop
Response:
- 200: Shop details retrieved successfully
- 404: Shop not foun

5.5 Logs

Endpoint: /logs

5.5.1 Get all shop logs

GET: /shops
Response:
- 200: Success response

5.5.2 Get specific shop logs

GET: /shops/{shop_id}
Parameters: -shop_id (Path Parameter, Required): Unique identifier for the shop
Response:
- 200: Success response

5.5.3 Download all shop logs

GET: /shops/download
Summary: Download all shop logs as a text file.
Response:
- 200: Success response

5.5.4 Download specific shop logs

GET: /shops/{shop_id}/download
Summary: Download all logs for specific shop
Response:
- 200: Success response

5.5.5 Get shop actions logs

GET: /shop/actions
Method: GET
Summary: Get shop action logs.
Response:
- 200: Success response

5.5.6 Download product logs

GET: /product/download
Summary: Download product logs.
Response:
- 200: Success response
- 500: Could not download audit logs

Download server logs

GET: /server/download
Summary: Download server logs for the current date
Response:
- 200: Success response
- 500: Could not download server logs

5.6 Notifications

Endpoint: /notification

5.6.1 Send mail to user

POST: /
Summary Send notifications to users
Response:
- 200: Email sent successfully
- 400: Bad request
- 424: Email not sent
- 500: an error occured during execution, try again

Database Schema

The Spitfire Superadmin API utilizes a PostgreSQL database to store and manage data efficiently. This schema defines the structure and relationships of the tables used to store information related to shops, products, vendors, and more. Tables: Shop table Product table Vendor table

Authentication

Every endpoint in this API is meant to be used by the super admin user. To access any of the endpoints, you will need an authentication token.

Error Handling

Errors are returned as JSON objects in the following format with their error code

{
  "error": "error name",
  "message": "error description"
}

The API will return 5 error types, with diffreent descriptions when requests fail;

400: Request unprocessable
403: Forbidden
404: resource not found
422: Bad Request
429: Too Many Requests(rate limiting)
500: Internal server error

Testing

Note: ensure you are connected to the internet before running tests and are in spitfire-events directory

# install test suite and HTTP requests library
$ pip install requests pytest

cd super_admin_1
$ pytest tests\* -v

Deployment

The super admin 1 App is hosted for live testing at [https://spitfire-superadmin-1.onrender.com].

Contributing

Commit Convention

Before you create a Pull Request, please check whether your commits comply with the commit conventions used in this repository.

When you create a commit we kindly ask you to follow the convention category(scope or module): message in your commit message while using one of the following categories:

feat / feature: all changes that introduce completely new code or new features
fix: changes that fix a bug (ideally you will additionally reference an issue if present)
refactor: any code related change that is not a fix nor a feature
docs: changing existing or creating new documentation (i.e. README, docs for usage of a lib or cli usage)
build: all changes regarding the build of the software, changes to dependencies or the addition of new dependencies
test: all changes regarding tests (adding new tests or changing existing ones)
ci: all changes regarding the configuration of continuous integration (i.e. github actions, ci system)
chore: all changes to the repository that do not fit into any of the above categories.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Appreciation and acknowledgments to contributors, libraries, or resources that helped in developing the API.

Name		Name	Last commit message	Last commit date
Latest commit History 834 Commits
.github		.github
health		health
super_admin_1		super_admin_1
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
api-documentation.md		api-documentation.md
collection.py		collection.py
fetch_data.py		fetch_data.py
insert_product.py		insert_product.py
requirements.txt		requirements.txt
run.py		run.py
runtime.txt		runtime.txt
swagger_config.yaml		swagger_config.yaml
utils.py		utils.py

License

Freeman-kuch/spitfire-super-admin-one

Folders and files

Latest commit

History

Repository files navigation

Spitfire Superadmin API Documentation

Table of Contents

1. Introduction

2. Features

3. Technologies Used

4. Getting Started

4.1 Prerequisites

4.1.1 Clone The Repository

4.1.2 Install Dependencies

4.1.3 Configure Environment Variables

4.1.4 Usage

5. API Endpoints

5.1 Shop

5.1.1 Get Information from the Shop Endpoint

5.1.2 Get information related to all shops

5.1.3 Get information related to a specific shop

5.1.4 Ban a vendor/shop by ID

5.1.5 Get a list of all temporarily banned vendors

5.1.6 Unban a vendor by ID

5.1.7 Restore a temporarily deleted shop by ID

5.1.8 Temporarily delete a shop and its associated products

5.1.9 Permanently delete a shop and its associated products

5.1.10 Retrieve temporarily deleted vendors

5.1.11 Retrieve details of a temporarily deleted vendor

5.1.12 Get all sanctioned shops

5.2 Product

5.2.1 Get information related to all products

5.2.2 Get information related to a product

5.2.3 Sanction a product

5.2.4 Get product statistics

5.2.5 Temporarily delete a product by ID

5.2.6 Permanently delete a product by ID

5.2.7 Restore a temporarily deleted product

5.2.8 Approve a product

5.2.9 Retrieve temporarily deleted products

5.2.10 Download product logs

5.3 Health

5.3.1 Check the availability of specified API endpoints

5.3.2 Retrieve the last health check log entry

5.4 Test

5.4.1 Create a new user

5.4.2 Get all users

5.4.3 Delete a user by ID

5.4.4 Cretae a new shop for a user

5.4.5 Get all shops

5.4.6 Get a specific shop by ID

5.5 Logs

5.5.1 Get all shop logs

5.5.2 Get specific shop logs

5.5.3 Download all shop logs

5.5.4 Download specific shop logs

5.5.5 Get shop actions logs

5.5.6 Download product logs

Download server logs

5.6 Notifications

5.6.1 Send mail to user

Database Schema

Authentication

Error Handling

Testing

Deployment

Contributing

Commit Convention

License

Acknowledgments

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages