Awesome
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.2 and Ruby 3.3.
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
- Feature flags support with a UI for management
- Code quality tools
- RSpec tests
- RSpec API Doc Generator
- API documentation following OpenAPI
- Docker support
How to use
- Clone this repo
- Install PostgreSQL in case you don't have it
- Install node. The expected node version is defined in
.nvmrc
file. - Install yarn. You can run
corepack enable
to install the required yarn binaries. Corepack is already included in newest node versions. - Run
bootstrap.sh
with the name of your project like./bin/bootstrap.sh --name=my_awesome_project
. - Run
yarn install
andyarn build --watch
. This bundles the JS assets in the administration site using esbuild. bundle exec rspec
and make sure all tests pass (non-headless mode) orHEADLESS=true bundle exec rspec
(headless mode)- Run
bin/dev
. - You can now try your REST services!
How to use with Docker
- Have
docker
anddocker-compose
installed (You can check this by doingdocker -v
anddocker-compose -v
) - Run
bootstrap.sh
with the name of your project and the-d
or--for-docker
flag like./bin/bootstrap.sh --name=my_awesome_project -d
- Run
./bin/bootstrap.sh --help
for the full details.
- Run
- (Optional) If you want to deny access to the database from outside of the
docker-compose
network, remove theports
key in thedocker-compose.yml
from thedb
service. - (Optional) Run the tests to make sure everything is working with:
bin/rspec .
. - You can now try your REST services!
See Docker docs for more info
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
commandsbin/rails console
- bin/web to run any
bash
commandsbin/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 documenting the schema in the classes
- Better Errors for a better error page
- Brakeman for security static analysis
- Byebug for debugging
- DelayedJob for background processing
- Devise for basic authentication
- Devise Token Auth for API authentication
- 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 splitting tests evenly based on execution time
- Letter Opener for previewing emails in the browser
- New Relic for monitoring and debugging
- Oj for optimized JSON
- Pagy for pagination
- Parallel Tests for running the tests in multiple cores
- Prosopite to detect N+1 queries
- Pry for enhancing the Ruby shell
- Puma for the web 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 serving the API documentation
- Rubocop for Ruby linting
- Sendgrid for sending emails
- Shoulda Matchers for 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 parallel execution. See docs
- Fullstack development. 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 generateconfig/brakeman.ignore
Impersonation
The rails_api_base
incorporates a user impersonation feature, allowing AdminUser
s to assume the identity of other User
s. This feature is disabled by default.
See Impersonation docs for more info
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
- After adding the project to CC, go to
Repo Settings
- On the
Test Coverage
tab, copy theTest Reporter ID
- Set the current value of
CC_TEST_REPORTER_ID
in the GitHub secrets and 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.
<img src="https://s3-us-west-1.amazonaws.com/rootstrap.com/img/rs.png" width="100"/>