Boilerplate Rails API

Boilerplate features

Project wiki: https://github.com/rubygarage/boilerplate/wiki

Handling JSON API URI query with Trailblazer nested operations

Operation	Description	HTTP request example
Api::V1::Lib::Operation::Filtering	Sets JSON API filtering with all_filters as default matcher	GET /users?filter[email-eq][email protected]&filter[name-cont]=son&match=any_filters
Api::V1::Lib::Operation::PerformFiltering	Provides JSON API filtering with ctx[:filter_options] options	GET /users?filter[email-eq][email protected]&filter[name-cont]=son&match=any_filters
Api::V1::Lib::Operation::Sorting	Sets JSON API sorting	GET /users?sort=name,-age
Api::V1::Lib::Operation::PerformOrdering	Provides JSON API sorting	GET /users?sort=name,-age
Api::V1::Lib::Operation::Inclusion	Provides JSON API inclusion of related resources. Dot-separated relationship path supporting not implemented at this time	GET /users?include=team,organization
Api::V1::Lib::Operation::Pagination	Provides JSON API pagination with offset strategy. Accepts AciveRelation or Array as collection. By default returns 25 items per page	GET /users?page[number]=1&page[size]=1

Trailblazer macroses

Macros	Description
Macro::Assign	Provides to assign into context value from other context/context chains
Macro::AddContractError	Provides to set custom error to namespaced contract
Macro::Contract::Schema	Provides to use Dry::Validation.Schema as operation contract
Macro::Decorate	Provides to decorate ctx object with specified decorator. Supports object or collection as model
Macro::Inject	Provides to set dependency injection in operations
Macro::LinksBuilder	Provides to proxy resource path to Service::JsonApi::Paginator and sets composed links into context
Macro::Model	Provides to assign model into context. Supports assign by relation chain, relation find_by
Macro::ModelRemove	Provides to destroy and delete model.
Macro::Renderer	Provides to render operation result with specified serializer with strict following Jsonapi specification
Macro::Semantic	Provides to set value of semantic marker (semantic_success or semantic_failure) into context
Macro::Policy	Set semantic marker semantic_failure to equel :forbidden and add errors if no policy

Services

Service	Description
Service::Pagy	Wrapes active record collection / array into Pagy
Service::JsonApi::Paginator	Buildes pagination links with Pagy
Service::JsonApi::ResourceSerializer	FastJson serializer factory
Service::JsonApi::ResourceErrorSerializer	Resource error serializer service with strict following Jsonapi specification
Service::JsonApi::HashErrorSerializer	Hash error serializer service with strict following Jsonapi specification
Service::JsonApi::UriQueryErrorSerializer	URI query error serializer service with strict following Jsonapi specification
Api::V1::Lib::Service::JsonApi::ColumnsBuilder	Auxiliary service for performing validation dependencies for filtering/sorting operations. Build collection with Api::V1::Lib::Service::JsonApi::Column instances

Constants

Constant	Description
JsonApi::Filtering::PREDICATES	Available JSON API filter predicates by column type
JsonApi::Filtering::OPERATORS	Available JSON API filter matchers
JsonApi::Pagination::MINIMAL_VALUE	Pagination per page configuration
Constants::TokenNamespace::SESSION	Session JWT token namespace
Constants::TokenNamespace::RESET_PASSWORD	Reset password JWT token namespace

Application base classes

Class	Description
ApplicationEndpoint	Base class that responsible for handling statuses of HTTP-responses, works with DefaultEndpoint concern
ApiController	Base application controller class that available for unauthorized users
ApplicationOperation	Base application operation class
ApplicationContract	Base application contract class. Use it for build/update entity. Otherwise use Dry::Validation.Schema
ApplicationDecorator	Base application decorator class
ApplicationSerializer	Base application serializer class
ApplicationWorker	Base application worker class

Upload files

Boilerplate used Shrine for upload files local and to S3. Create you own uploader and inherit it from ApplicationUploader. For more info

Docker

Install docker and docker-compose

sudo apt-get install docker docker-compose

Run the project

docker-compose up

Running the tests

bin/docker rspec

Building API documentation

Generate a request spec file:

rails generate rspec:swagger API::MyController

Building api documentation is pretty easy, just run:

rake rswag

and find it into:

./api-docs/index.html

Running Rails console

bin/docker rails c

Running linters

lefthook run all

Using DIP

You can develop you application with DIP(more info)

For running services with docker.

dip run `the name of service`

Launch application with all services.

dip provision

List all available run commands.

dip ls

Sentry Notifire

To start work with sentry you should add dsn key to credentials under sentry_dsn name.

To get first error with Sentry raise Raven.capture_exception with exception as an argument.

More information here

Password complexity for User

Must contain at least 8 characters, of which: At list one upper case, at list one lowe case,

at list one number, at list one special symbols from the list: -_!@#$%^&*.

For example: qwertY1@