Rails API Template

Rails Api Base is a boilerplate project for JSON RESTful APIs. It follows the community best practices in terms of standards, security and maintainability, integrating a variety of testing and code quality tools. It's based on Rails 7.0 and Ruby 3.2.

Finally, it contains a plug an play Administration console (thanks to ActiveAdmin).

Features

This template comes with:

• Schema
  • Users table
  • Admin users table
• Endpoints
  • Sign up with user credentials
  • Sign in with user credentials
  • Sign out
  • Reset password
  • Get and update user profile
• Administration panel for users
• Feature flags support with a UI for management.
• RSpec tests
• Code quality tools
• API documentation following https://www.openapis.org/
• RSpec API Doc Generator
• Docker support

How to use

1. Clone this repo
2. Install PostgreSQL in case you don't have it
3. Install node and yarn.
4. Run bootstrap.sh with the name of your project like ./bootstrap.sh --name=my_awesome_project
5. rspec and make sure all tests pass
6. Run rails s.
7. Run yarn install and yarn build --watch. This bundles the JS assets in the administration site using esbuild.
8. You can now try your REST services!

How to use with docker

1. Have docker and docker-compose installed (You can check this by doing docker -v and docker-compose -v)
2. Run bootstrap.sh with the name of your project and the -d or --for-docker flag like ./bootstrap.sh --name=my_awesome_project -d
   1. Run ./bootstrap.sh --help for the full details.
3. Generate a secret key for the app by running bin/web rake secret, copy it and add it in your environment variables.
4. (Optional) If you want to deny access to the database from outside of the docker-compose network, remove the ports key in the docker-compose.yml from the db service.
5. (Optional) Run the tests to make sure everything is working with: bin/rspec ..
6. You can now try your REST services!

Dev scripts

This template provides a handful of scripts to make your dev experience better!

• bin/bundle to run any bundle commands.
  • bin/bundle install
• bin/rails to run any rails commands
  • bin/rails console
• bin/web to run any bash commands
  • bin/web ls
• bin/rspec to run specs
  • bin/rspec .
• bin/dev to run both rails and JS build processes at the same time in a single terminal tab.
  • bin/dev

You don't have to use these but they are designed to run the same when running with docker or not. To illustrate, bin/rails console will run the console in the docker container when running with docker and locally when not.

Gems

• ActiveAdmin for easy administration
• Arctic Admin for responsive active admin
• Annotate for doc the schema in the classes
• Better Errors for a better error page
• Brakeman for static analysis security
• Byebug for debugging
• DelayedJob for background processing
• Devise for basic auth
• Devise Token Auth for api auth
• Dotenv for handling environment variables
• Draper for decorators
• Factory Bot for testing data
• Faker for generating test data
• Flipper for feature flag support
• Jbuilder for json views
• JS Bundling for bundling JS assets.
• Knapsack for generating CI time report and splitting into nodes
• Letter Opener for previewing a mail in the browser
• New Relic for monitoring and debugging
• Oj for optimized json
• Pagy for pagination
• Parallel Tests for split CI in several cores
• Prosopite to detect N+1 queries
• Pry for enhancing the ruby shell
• Puma for the server
• Pundit for authorization management
• Rack CORS for handling CORS
• Rails Best Practices for rails linting
• Reek for ruby linting
• RSpec for testing
• RSpec OpenAPI for generating API documentation
• Rswag for expose API documentation
• Rubocop for ruby linting
• Sendgrid for sending mails
• Shoulda Matchers adds other testing matchers
• Simplecov for code coverage
• Strong Migrations for catching unsafe migrations in development
• Webmock for stubbing http requests
• YAAF for form objects

Optional configuration

• Set your frontend URL in config/initializers/rack_cors.rb
• Set your mail sender in config/initializers/devise.rb
• Config your timezone accordingly in application.rb.
• Config CI in parallel execution. See docs.

Api Docs

• RSpec API Doc Generator you can generate the docs after writing requests specs.
• Rswag you can expose the generated docs.

See api_documentation docs for more info.

Code quality

With bundle exec rails code:analysis you can run the code analysis tool, you can omit rules with:

• Rubocop Edit .rubocop.yml
• Reek Edit config.reek
• Rails Best Practices Edit config/rails_best_practices.yml
• Brakeman Run brakeman -I to generate config/brakeman.ignore

Monitoring

In order to use New Relic to monitor your application requests and metrics, you must setup NEW_RELIC_API_KEY and NEW_RELIC_APP_NAME environment variables. To obtain an API key you must create an account in the platform.

Configuring Code Climate

1. After adding the project to CC, go to Repo Settings
2. On the Test Coverage tab, copy the Test Reporter ID
3. Set the current value of CC_TEST_REPORTER_ID in the circle-ci project env variables

Code Owners

You can use CODEOWNERS file to define individuals or teams that are responsible for code in the repository.

Code owners are automatically requested for review when someone opens a pull request that modifies code that they own.

Credits

Rails Api Base is maintained by Rootstrap with the help of our contributors.