/go-api-router

:globe_with_meridians: A lightweight API middleware for Julien Schmidt's router: cors, logging, and standardized error handling

Primary LanguageGoMIT LicenseMIT

🌐 go-api-router

Lightweight API httprouter middleware: cors, logging, and standardized error handling.

CI / CD Quality & Security Docs & Meta Community
Latest Release
Build Status
CodeQL
Last commit 		Go Report Card
Code Coverage
OpenSSF Scorecard
Security policy
OpenSSF Best Practices 		Go version
Go docs
AGENTS.md rules
MAGE-X Supported
Dependabot 		Contributors
Sponsor
Donate Bitcoin

🗂️ Table of Contents


📦 Installation

go-api-router requires a supported release of Go.

go get github.com/mrz1836/go-api-router

📚 Documentation

View the generated documentation

GoDoc

Features

  • Uses the fastest router: Julien Schmidt's httprouter
  • Uses gofr's uuid package to guarantee unique request ids
  • Uses MrZ's go-logger for either local or remote logging via Log Entries (Rapid7)
  • Uses MrZ's go-parameters for parsing any type of incoming parameter with ease
  • Optional: NewRelic support!
  • Added basic middleware support from Rileyr's middleware
  • Optional: JWT Authentication (middleware)
  • Added additional CORS functionality
  • Standardized error responses for API requests
  • Centralized logging on all requests (requesting user info and request time)
  • Custom response writer for Etag and cache support
  • GetClientIPAddress() safely detects IP addresses behind load balancers
  • GetParams() parses parameters only once
  • FilterMap() removes any confidential parameters from logs
  • ...and more!
Development Setup (Getting Started)

Install MAGE-X build tool for development:

# Install MAGE-X for development and building
go install github.com/mrz1836/mage-x/cmd/magex@latest
magex update:install
Library Deployment

This project uses goreleaser for streamlined binary and library deployment to GitHub. To get started, install it via:

brew install goreleaser

The release process is defined in the .goreleaser.yml configuration file.

Then create and push a new Git tag using:

magex version:bump bump=patch push

This process ensures consistent, repeatable releases with properly versioned artifacts and citation metadata.

Build Commands

View all build commands

magex help
GitHub Workflows

🎛️ The Workflow Control Center

All GitHub Actions workflows in this repository are powered by configuration files: .env.base (default configuration) and optionally .env.custom (project-specific overrides) – your one-stop shop for tweaking CI/CD behavior without touching a single YAML file! 🎯

Configuration Files:

  • .env.base – Default configuration that works for most Go projects
  • .env.custom – Optional project-specific overrides

This magical file controls everything from:

  • 🚀 Go version matrix (test on multiple versions or just one)
  • 🏃 Runner selection (Ubuntu or macOS, your wallet decides)
  • 🔬 Feature toggles (coverage, fuzzing, linting, race detection, benchmarks)
  • 🛡️ Security tool versions (gitleaks, nancy, govulncheck)
  • 🤖 Auto-merge behaviors (how aggressive should the bots be?)
  • 🏷️ PR management rules (size labels, auto-assignment, welcome messages)

Pro tip: Want to disable code coverage? Just add ENABLE_CODE_COVERAGE=false to your .env.custom to override the default in .env.base and push. No YAML archaeology required!


Workflow Name Description
auto-merge-on-approval.yml Automatically merges PRs after approval and all required checks, following strict rules.
codeql-analysis.yml Analyzes code for security vulnerabilities using GitHub CodeQL.
dependabot-auto-merge.yml Automatically merges Dependabot PRs that meet all requirements.
fortress.yml Runs the GoFortress security and testing workflow, including linting, testing, releasing, and vulnerability checks.
pull-request-management.yml Labels PRs by branch prefix, assigns a default user if none is assigned, and welcomes new contributors with a comment.
scorecard.yml Runs OpenSSF Scorecard to assess supply chain security.
stale.yml Warns about (and optionally closes) inactive issues and PRs on a schedule or manual trigger.
sync-labels.yml Keeps GitHub labels in sync with the declarative manifest at .github/labels.yml.
Updating Dependencies

To update all dependencies (Go modules, linters, and related tools), run:

magex deps:update

This command ensures all dependencies are brought up to date in a single step, including Go modules and any managed tools. It is the recommended way to keep your development environment and CI in sync with the latest versions.


🧪 Examples & Tests

All unit tests and fuzz tests run via GitHub Actions and use Go version 1.24.x. View the configuration file.

Run all tests (fast):

magex test

Run all tests with race detector (slower):

magex test:race

⚡ Benchmarks

Run the Go benchmarks:

magex bench

🛠️ Code Standards

Read more about this Go project's code standards.


🤖 AI Compliance

This project documents expectations for AI assistants using a few dedicated files:

  • AGENTS.md — canonical rules for coding style, workflows, and pull requests used by Codex.
  • CLAUDE.md — quick checklist for the Claude agent.
  • .cursorrules — machine-readable subset of the policies for Cursor and similar tools.
  • sweep.yaml — rules for Sweep, a tool for code review and pull request management.

Edit AGENTS.md first when adjusting these policies, and keep the other files in sync within the same pull request.


👥 Maintainers

MrZ
MrZ

🤝 Contributing

View the contributing guidelines and please follow the code of conduct.

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬. You can also support this project by becoming a sponsor on GitHub 👏 or by making a bitcoin donation to ensure this journey continues indefinitely! 🚀

Stars


📝 License

License