commerce-api

A RESTful API written in Rust (specifically using axum) to serve as the backend for a commerce web application. All data is stored in a PostgreSQL database and accessed through diesel. Supports custom session cookie based user auth.
Explore the docs

View Demo . Report Bug . Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact

About The Project

(back to top)

Built With

• 
• 
• 
• 

(back to top)

Getting Started

To get a local copy up and running follow these simple steps.

Prerequisites

To run this api, you will need to have cargo installed, and PostgreSQL setup

• Cargo installation docs
• PostgreSQL download page

After installing postgres, make sure you setup a database to be used with the api, e.g.

CREATE DATABASE commerce; -- Where commerce cand be any name you want

Side Note:

I also highly recommend cargo-watch for allowing live reloads on the server as changes are saved. If you do go this route, don't forget to ignore the log folder or cargo will just keep restarting the server!

Installation

1. Clone the repo

   git clone https://github.com/quasiuslikecautious/commerce-api.git

2. Install cargo crates

   cargo build

3. Install the diesel CLI and initialize diesel in the project

   # run this command in the project root e.g. .../commerce-api/
   cargo install diesel_cli
   diesel setup

4. Setup your .env file with the database path and secrets

   echo DATABASE_URL=postgres://username:password@localhost/diesel_demo > .env
   echo JWT_SECRET=<Some Secret Value>
   echo SESSION_SECRET=<Some Secret Value>
   echo NONCE_SECRET=<Some Secret Value>

5. Initialize your database with the tables this project will use

   diesel migration run

6. Finally, generate a certificate for the server to use for https. I won't get into the weeds on how to generate the certificate, but I highly recommend this blog if you need any help. The only requirements the server has on the certificate, is that they are stored in .../self_signed_certs/localhost.crt, and .../self_signed_certs/localhost.key path.

(back to top)

Usage

To use this API, simply run

cargo run # default run command
# OR
cargo watch -x run -i log # if you have cargo-watch installed and want live reloads

in the project's root, and the server will start up.

By default, the server runs http redirection on port 7878, and the https api on port 8000, though this can be changed by specifying the HTTP_PORT variable for the http redirection port, and HTTPS_PORT variable for the https api port in the .env file.

Additionally, as this API employs logging, log files will be generated in the .../log path, storing up to 10 50kb log files with commerce.log being the most recent log file, and commerce10.log being the oldest. The log level (default is INFO) and other logging settings can be edited in .../logging_config.yaml

Example Auth Flow

    # start up server
    cargo run

    # to make requests to the server, as the certs will be self signed we
    # need to set the --insecure flag. Additionally, as session management
    # is cookie based, we must store and use cookies, hence the '-b' and 'c'
    # need to be set to the same file.

    curl --insecure https://127.0.0.1:8000/api/v1/auth/nonce \
        -c cookies.txt -b cookies.txt
    # user receives 401 status code and nonce in response, e.g.
    # 401 Unauthorized
    # { "nonce": <Some nonce> }

    curl --insecure https://127.0.0.1:8000/api/v1/auth/signin \
        -H 'Content-Type: application/json' \
        -d '{"email": "commerce-api@example.com", "password": "password", "nonce": <nonce returned from /nonce request>}' \
        -c cookies.txt -b cookies.txt
    # user session id is stored in db and user session cookie is now auth'd

For more examples, please refer to the Documentation TODO will add link to API docs here

(back to top)

Roadmap

• Add a README
  • Link API docs once created to usage section
• Add BASIC Authentication over https
  • Use session-cookie based user auth instead of JWTs
  • Add nonce for authentication
    • Fix custom implemented session store to save session if new
• Add OAuth 2.0 auth instead
  • Set up extractors on routes for grabbing/guarding routes
• Add pagination for /items route and future multi item return routes
• Reuse JWT for external API authentication
• Encrypt data at rest
• Add db cleanup jobs for session based user auth
  • Add truncate table function
  • Determine how often/triggers for running cleanup jobs
• Add documentation to crate
• Add unit tests
• Add api documentation (openapi)
• Move db ops out of main loop and into struct files
• [ ]

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Your Name - @zquasius - zach@quasius.dev@gmail.com

Project Link: https://github.com/quasiuslikecautious/commerce-api

(back to top)