Have ideas to improve npm?Join in the discussion! »

    rails-ranger

    1.2.0 • Public • Published

    Rails Ranger

    Exploring the routes and paths of Ruby on Rails APIs

    Github Repository | Documentation

    npm version Travis build status Test Coverage Dependency Status devDependency Status

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

    Main features

    • URL building following Ruby on Rails routes conventions
    • Automatic transformation of camelCase into snake_case and back to camelCase when exchanging data between the front-end and the API

    Installation

    npm install --save rails-ranger

    or

    yarn add rails-ranger

    Getting started

    If you prefer a blog post, checkout our getting started guide here.

    The following example illustrates a simple usage of the library:

    // api-client.js
    import RailsRanger from 'rails-ranger'
     
    const config = {
      axios: {
        baseURL: 'http://api.myapp.com',
        headers: {
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        }
      }
    }
     
    export default new RailsRanger(config)
    // some-front-end-component.js
    import api from 'api-client'
     
    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.

    Important notice for non api-only Ruby on Rails servers

    You must setup the headers correctly, passing down the content type and accept keys as application/json (as shown in the example above) for Rails to serve the endpoint in the json format instead of presuming the HTTP default.

    A slightly more advanced example:

    api.resource(users, 1).list('blogPosts', { someParameter: false })
    // => GET request to /users/1/blog_posts?some_parameter=false

    Build your own client object

    You can build your own client object to centralize the API routes used by your front-end app.

    This is indeed highly recommended for non-trivial applications, to avoid duplication, get better control of the API client interface and make your life easier in the event of you wanting to remove/replace this dependency from your project.

    Below is an example of such implementation:

    // api-client.js
    import RailsRanger from 'rails-ranger'
     
    const client = new RailsRanger
     
    export default {
      client,
     
      users: {
        list(params) {
          return this.client.list('users', params)
        }
      }
     
      blogPosts: {
        list(params) {
          return this.client.list('blogPosts', params)
        }
      }
    }
    // some-front-end-component.js
    import api from 'api-client'
     
    api.users.list({ limit: 3 }).then((response) => {
      const users = response.data
    })

    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 the client.

    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 back from snake_case to camelCase for better usage within your javascript code.

    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 an example using the baseUrl configuration of Axios:

    const api = new RailsRanger({ axios: { baseUrl: 'http://myapp.com/api/v1' } })
     
    api.list('users')
    // => GET request to http://myapp.com/api/users

    See more configuration options in the Axios documentation


    Use Rails Ranger just for path building

    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 resource routes and then make the request with another tool. The following is an example of this usage:

    import { RouteBuilder } from RailsRanger
    const routes = new RouteBuilder
     
    routes.create('users', { name: 'John' })
    // => { path: '/users', params: { name: 'John' }, method: 'post' }
     
    routes.show('users', { id: 1, hidePassword: true })
    // => { path: '/users/1?hide_password=true', params: {}, method: 'get' }
     
    routes.get('/:api/documentation', { api: 'v1', page: 3 })
    // => { path: 'v1/documentation?page=3', params: {}, method: 'get' }

    Nested resources

    You can access your nested resources by using the .resource function:

    api.resource('users').list('blogPosts')
    //=> GET request to /users/blog_posts
     
     
    api.resource('users', 1).list('blogPosts')
    //=> GET request to /users/1/blog_posts

    Namespaced routes

    The .namespace function can help you to build a path nested within a Rails namespace:

    api.namespace('users').list('blogPosts')
    //=> GET request to /users/blog_posts
     
     
    api.namespace('admin_roles/:type', { type: 1 }).list('blogPosts')
    //=> GET request to /admin_roles/1/blog_posts

    Available actions

    List/Index

    api.list('users', { limit: 3 })
    // => GET request to /users?limit=3
     
    api.index('users', { limit: 3 })
    // => GET request to /users?limit=3

    Show

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

    New

    api.new('users')
    // => GET request to /users/new

    Create

    api.create('users', { email: 'john@doe.com' })
    // => POST request to /users

    Edit

    api.edit('users', { id: 1 })
    // => GET request to /users/1/edit

    Update

    api.update('users', { id: 1, name: 'John Doe' })
    // => PATCH request to /users/1

    Destroy

    api.destroy('users', { id: 1 })
    // => DELETE request to /users/1

    Available HTTP methods

    GET

    api.get('users/:id', { id: 1, hidePassword: true })
    // => GET request to users/1&hide_password=true

    POST

    api.post('users/:id', { id: 1, name: 'John' })
    // => POST request to users/1 with a JSON payload containing: { "name": "John" }

    PATCH

    api.patch('users/:id', { id: 1, name: 'John' })
    // => PATCH request to users/1 with a JSON payload containing: { "name": "John" }

    PUT

    api.put('users/:id', { id: 1, name: 'John' })
    // => PUT request to users/1 with a JSON payload containing: { "name": "John" }

    DELETE

    api.delete('users/:id', { id: 1, hidePassword: true })
    // => DELETE request to users/1&hide_password=true

    Keywords

    none

    Install

    npm i rails-ranger

    DownloadsWeekly Downloads

    24

    Version

    1.2.0

    License

    MIT

    Unpacked Size

    2.73 MB

    Total Files

    76

    Last publish

    Collaborators

    • avatar