grape-api-boilerplate

A full-featured, production ready, and easy to understand API boilerplate for the Grape framework.

Features

• Local development with Docker and Docker Compose.
• Automatic Puma reloading locally with guard-puma.
• ActiveRecord with otr-activerecord.
• Swagger API documentation with grape-swagger.
• User authentication with bcrypt using jwt.
• Model pagination with api-pagination.
• Standard security headers with secure_headers.
• Monitoring and alerting with Sentry andPrometheus.
• Comprehensive RSpec test suite and code coverage.

Running

• Generate a key pair for local JWT authentication.

cd grape-api-boilerplate/config/jwt
ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub

• Build and run with Docker Compose.

docker compose up --build

• Setup and seed the database.

docker compose exec app bundle exec rake db:setup

• Visit your API at http://localhost:3000

Creating a user

• Run the create users Rake task.

docker compose run --rm app bundle exec rake users:create

• Enter your desired email, username, and password.

Authentication and requests

• Hello world.

curl http://localhost:3000/api/v1/hello | jq .

• Authenticate and authenticated request.

# Authenticate with the test user.
token=$(curl -XPOST \
  -H "Content-Type:application/json" \
  -d '{"username":"grape_user","password":"grape_user1"}' \
  http://localhost:3000/api/login | jq -r '.token')

curl -H "Authorization: Bearer ${token}" \
  http://localhost:3000/api/v1/widget | jq .

Tests

• Run linting and tests.

docker compose run --rm -e RACK_ENV=test app bundle exec rake

API documentation

When running locally, you can visit http://localhost:3000/public/swagger/index.html to view your Swagger API documentation.

Production

Sentry

You can enable Sentry for your API by setting sentry.enabled in your settings file(s).

• Update the setting in app/settings/<environment>.yml.

sentry:
  enabled: true

• Add your Sentry DSN to a SENTRY_DSN environment variable.

• See the Sentry Rack guide for more.

Prometheus

You can enable Prometheus metrics for your API by setting prometheus.enabled in your production settings file.

• Update the setting in app/settings/production.yml.

prometheus:
  enabled: true

• The default middleware will provide some basic metrics out of the box. See the Ruby Prometheus client library documentation for advanced usage.

Note: Prometheus metrics should not be exposed publicly! Please ensure you know what you're doing before enabling this feature in your environment.

Docker

Build a production ready image with the Dockerfile and deploy to your favorite platform.

docker build -t grape-api-boilerplate:latest .

Contributing

Contributions are welcome! See CONTRIBUTING.

License

MIT License. See LICENSE for details.