api

Table of Contents

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

About

This project provides a well-structured API using Go and the Gin framework. It includes authentication, key-based validation, and user management features. The implementation follows a modular architecture:

• Cmd: Contains the main.go file to run the API

• Config: Initializes application configuration files. Modify or add cusom config files to set up custom services

• Internals: Handle request validation, authentication, and error handling. Modify or add custom middleware for additional security, logging, or app-wide features

• Modules: Custom-defined API modules, all being served from the same API. Modify these as you desire according to the Gin framework!

(back to top)

Built With

• Golang
• Gin
• JWT Authentication

(back to top)

Getting Started

Prerequisites

• Go (v1.24)
• Git

Installation

1. Clone the repo

git clone https://github.com/ethanbaker/api.git

1. Navigate to project folder

cd api

1. Install dependencies

go mod tidy

1. Implement custom modules in the modules/ directory. You can import module routes into the cmd/main.go file

2. Set up environment variables in .env file as needed for your API

PORT=8080
DB_URI=your_database_connection_string
JWT_SECRET=your_secret_key
...

1. Start the server

go run cmd/main.go

(back to top)

Usage

Health Module (Open Endpoint)

This module serves as a basic health check. It returns an "ok" message when queried, confirming that the API is running. This is the most basic API route with no protection.

curl -X GET 'http://localhost:8080/health/status'

Response:

{"message":"ok"}

Key Module (API Key Validation)

This module verifies API keys. A request will only succeed if a valid API key is included in the request headers.

Successful API Query:

curl -X GET 'http://localhost:8080/key/response' -H 'X-API-KEY: 1234567890'

Response:

{"message":"ok"}

Invalid API Query:

curl -X GET 'http://localhost:8080/key/response' \
    -H 'X-API-KEY: invalid-key'

Response:

{"message":"Forbidden"}

User Module (JWT Authentication)

This module tests user authentication with JWT. Users must log in to receive a token, which is required to access protected endpoints.

Successful Unprotected Query:

curl -X GET 'http://localhost:8080/users/anon-response'

Response:

{"message":"Hello anonymous!"}

Invalid Protected Query:

curl -X GET 'http://localhost:8080/users/response'

Response:

{"message":"cookie token is empty"}

Successful Login Attempt:

curl -X POST 'http://localhost:8080/users/auth/login' \
    -H 'Content-Type: application/json' \
    -d '{"username": "admin", "password": "admin"}'

Response:

{"code":200,"expire":"YYYY-MM-DDTHH:MM:SSZ","token":"JWT_TOKEN"}

Successful Protected Query:

curl -X GET 'http://localhost:8080/users/response' \
    -H 'Authorization: Bearer JWT_TOKEN'

Response:

{"message":"Hello admin!","username":"admin"}

For more examples, please refer to the documentation.

(back to top)

Roadmap

• Docker Containerization
• Comprehensive MySQL Integration

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

(back to top)

Contributing

For issues and suggestions, please include as much useful information as possible. Review the documentation and make sure the issue is actually present or the suggestion is not included. Please share issues/suggestions on the issue tracker.

For patches and feature additions, please submit them as pull requests. Please adhere to the conventional commits. standard for commit messaging. In addition, please try to name your git branch according to your new patch. These standards are a great guide you can follow.

You can follow these steps below to create a pull request:

1. Fork the Project
2. Create your Feature Branch (git checkout -b branch_name)
3. Commit your Changes (git commit -m "commit_message")
4. Push to the Branch (git push origin branch_name)
5. Open a Pull Request

(back to top)

License

This project uses the MIT License.

You can find more information in the LICENSE file.

(back to top)

Contact

Ethan Baker - contact@ethanbaker.dev - LinkedIn

Project Link: https://github.com/ethanbaker/api

(back to top)