Rails Ranger

Exploring the routes and paths of Rails APIs

This library development is in a very early stage and the API is VERY unstable

Github Repository | Documentation

npm version Travis build status Test Coverage Dependency Status devDependency Status Stories in Ready

Rails Ranger is a thin layer on top of Axios, which gives you an opinionated interface to query APIs built with Ruby on Rails.

Installation

npm install --save rails-ranger

or

yarn add rails-ranger


How does it work?

The following should serve as a simple illustration of the library API:

import RailsRanger from 'rails-ranger'

const api = new RailsRanger({
  axios: { baseURL: 'http://api.myapp.com' }
})

api.list('users').then((response) => {
  const users = response.data
})

The list function makes a request to the index path of the users resource, following Rails routing conventions. This means a GET request to the /users path.

Also we converted the snake_cased JSON generated by Ruby on Rails automaticaly to camelCase, as preferred in Javascript.

Observation: you can use api.index('users') as well. The list function is just an alias for it.

A slightly more complex example:

api.show('users', { id: 1, expanded: false })
// => GET request to /users/1?expanded=false


Options

As the first argument when creating a new instance of Rails Ranger you can pass an object of options to customize the behavior of Rails Ranger.

dataTransform

default: true

By default RailsRanger will convert camelCased keys in your jsons to snake_case when sending a request to Rails, and will convert the Rails response from snake_case to camelCase for you to use in your front-end.

You can disable this behavior by setting dataTransform to false:

const api = new RailsRanger({ dataTransform: false })

axios

default: {}

Any object passed to the axios option will be handled to Axios. Here are some usage examples:

Base URL

const api = new RailsRanger({ axios: { baseUrl: 'http://myapp.com/api' } })

api.list('users')
// => GET request to http://myapp.com/api/users

Timeout

const api = new RailsRanger({ axios: { timeout: 3000 } })

api.list('users') // => Will timeout within 3000 miliseconds

See more in the Axios documentation


Using Rails Ranger just for building routes

You don't need to use Rails Ranger as an ajax client if you don't want to. It can also be used just to generate the routes from your resources. To use Rails Ranger this way you can do the following:

import { RouteBuilder } from RailsRanger
const route = new RouteBuilder

route.create('users', { name: 'John' })
// => { path: '/users', params: { name: 'John' }, method: 'post' }

route.show('users', { id: 1, hidePassword: true })
// => { path: '/users/1?hide_password=true', params: {}, method: 'get' }

route.get('/:api/documentation', { api: 'v1', page: 3 })
// => { path: 'v1/documentation?page=3', params: {}, method: 'get' }

Actions (pending)

  • list/index
  • show
  • new
  • create
  • edit
  • update

Methods (pending)

  • GET
  • POST
  • PATCH
  • PUT
  • DELETE