Go-API Template

A modular implementation of a golang API with Gin

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. Inside the pkg directory, there are numerous external packages you can use in your custom APIs. In addition, you can clone and modify these packages as needed.

The idea of this project is to serve multiple different API functionalities (dubbed modules) from the same instance (or URL if you're self hosting). Each module should be its own use case and shouldn't require direct overlap with other modules. For example, you should separate a personal budget API schema into one module and a netflix movie catalog API schema into a different module. You should not separate related functionality, such as transactions and invoice endpoints for one project, as they probably use common types (Transaction, Invoice, etc).

The general implementation follows a modular architecture in the template directory:

• internal: Handle shared functionality between modules. For example, if you are running an API to serve multiple customer sites, you'll probably need different modules for each site's specifications. But, if all sites implement a chat-bot feature, you could create one common package in the internal directory to house this

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

• docs: Contain documentation (markdown files, word files, images, etc) for your API

• main.go: Set global configuration settings and run your API!

(back to top)

Built With

• Golang
• Gin
• JWT Authentication

(back to top)

Getting Started

Prerequisites

• Go (v1.24)
• Git

Installation

Install instructions are written in bash for simplicity.

1. Clone the repo

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

2. Navigate to project folder

cd api

3. Copy template folder to your intended destination

cp -r templates/ ...

4. Implement custom modules in the modules/ directory. You can import module routes into the main.go file. You can import pkg libraries from this repository directly or modify them from the clone and add them to internal/ in your template

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

PORT=8080
JWT_SECRET=your_secret_key
...

6. Start the server

go run main.go

(back to top)

Usage

Example endpoints and pkg library usage can be found in the example directory.

In order for the users module to properly work, you must supply a .env file with a value for JWT_SECRET.

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'

Response:

{"status":"success","code":200,"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:

{"status":"success","code":200,"message":"API Key is valid"}

Invalid API Query:

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

Response:

{"status":"fail","code":403,"message":"","error":"Invalid API Key"}

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:

{"status":"success","code":200,"message":"Hello, anonymous user!"}

Invalid Protected Query:

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

Response:

{"status":"fail","code":401,"message":"","error":"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:

{"status":"success","code":200,"message":"Hello admin!","data":{"username":"admin"}}

For more examples, please refer to the documentation.

(back to top)

Roadmap

• Generalizable package
• Cmd scaffolding tool
• 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)