{"id":13760283,"url":"https://github.com/victor-am/rails-ranger","last_synced_at":"2025-08-16T23:48:52.262Z","repository":{"id":48053178,"uuid":"91917857","full_name":"victor-am/rails-ranger","owner":"victor-am","description":"🤠 An opinionated AJAX client for Ruby on Rails APIs","archived":false,"fork":false,"pushed_at":"2021-08-09T20:37:23.000Z","size":1983,"stargazers_count":32,"open_issues_count":3,"forks_count":5,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-09T13:59:22.297Z","etag":null,"topics":["ajax","ajax-client","axios","javascript","rails","rails-api","rest-client"],"latest_commit_sha":null,"homepage":"https://victor-am.github.io/rails-ranger/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/victor-am.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-20T21:41:35.000Z","updated_at":"2024-02-08T19:53:45.000Z","dependencies_parsed_at":"2022-08-12T17:31:22.502Z","dependency_job_id":null,"html_url":"https://github.com/victor-am/rails-ranger","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/victor-am/rails-ranger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/victor-am%2Frails-ranger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/victor-am%2Frails-ranger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/victor-am%2Frails-ranger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/victor-am%2Frails-ranger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/victor-am","download_url":"https://codeload.github.com/victor-am/rails-ranger/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/victor-am%2Frails-ranger/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270786282,"owners_count":24644562,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-16T02:00:11.002Z","response_time":91,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ajax","ajax-client","axios","javascript","rails","rails-api","rest-client"],"created_at":"2024-08-03T13:01:06.785Z","updated_at":"2025-08-16T23:48:52.189Z","avatar_url":"https://github.com/victor-am.png","language":"JavaScript","funding_links":[],"categories":["API","API [🔝](#readme)"],"sub_categories":["Runner","运行器","运行器e2e测试"],"readme":"# Rails Ranger\n### Exploring the routes and paths of Ruby on Rails APIs\n\n#### [Github Repository](https://github.com/victor-am/rails-ranger) | [Documentation](https://victor-am.github.io/rails-ranger)\n\n[![npm version](https://badge.fury.io/js/rails-ranger.svg)](https://badge.fury.io/js/rails-ranger)\n[![Travis build status](http://img.shields.io/travis/victor-am/rails-ranger.svg?style=flat)](https://travis-ci.org/victor-am/rails-ranger)\n[![Test Coverage](https://codeclimate.com/github/victor-am/rails-ranger/badges/coverage.svg)](https://codeclimate.com/github/victor-am/rails-ranger)\n[![Dependency Status](https://david-dm.org/victor-am/rails-ranger.svg)](https://david-dm.org/victor-am/rails-ranger)\n[![devDependency Status](https://david-dm.org/victor-am/rails-ranger/dev-status.svg)](https://david-dm.org/victor-am/rails-ranger#info=devDependencies)\n\nRails Ranger is a thin layer on top of [Axios](https://github.com/mzabriskie/axios), which gives you an opinionated interface to query APIs built with Ruby on Rails.\n\n## Main features\n- URL building following Ruby on Rails routes conventions\n- Automatic transformation of camelCase into snake_case and back to camelCase when exchanging data between the front-end and the API\n\n\n## Installation\n```bash\nnpm install --save rails-ranger\n```\n\n**or**\n\n```bash\nyarn add rails-ranger\n```\n\u003cbr\u003e\n\n## Getting started\nIf you prefer a blog post, checkout our [getting started guide here](https://alligator.io/js/rails-ranger/).\n\nThe following example illustrates a simple usage of the library:\n\n```javascript\n// api-client.js\nimport RailsRanger from 'rails-ranger'\n\nconst config = {\n  axios: {\n    baseURL: 'http://api.myapp.com',\n    headers: {\n      'Content-Type': 'application/json',\n      'Accept': 'application/json'\n    }\n  }\n}\n\nexport default new RailsRanger(config)\n```\n\n```javascript\n// some-front-end-component.js\nimport api from 'api-client'\n\napi.list('users').then((response) =\u003e {\n  const users = response.data\n})\n```\n\nThe `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.\n\nAlso we converted the *snake_cased* JSON generated by Ruby on Rails automatically to *camelCase*, as preferred in Javascript.\n\n\u003e **Observation:** you can use `api.index('users')` as well. The `list` function is just an alias for it.\n\u003cbr\u003e\n\n### Important notice for non api-only Ruby on Rails servers\nYou 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.\n\n### A slightly more advanced example:\n\n```javascript\napi.resource(users, 1).list('blogPosts', { someParameter: false })\n// =\u003e GET request to /users/1/blog_posts?some_parameter=false\n```\n\u003cbr\u003e\n\n### Build your own client object\nYou can build your own client object to centralize the API routes used by your front-end app.\n\nThis is indeed **recommended** for non-trivial applications, to avoid duplication, allow manipulating the parameters before performing the request and make your life easier in the event of removal/replacement of this dependency from your project.\n\nBelow is an example of such implementation:\n\n```javascript\n// api-client.js\nimport RailsRanger from 'rails-ranger'\n\nconst client = new RailsRanger\n\nexport default {\n  users: {\n    list(params) {\n      return client.list('users', params)\n    }\n  }\n\n  blogPosts: {\n    list(params) {\n      return client.list('blogPosts', params)\n    }\n  }\n}\n```\n\n```javascript\n// some-front-end-component.js\nimport api from 'api-client'\n\napi.users.list({ limit: 3 }).then((response) =\u003e {\n  const users = response.data\n})\n```\n\u003cbr\u003e\n\n## Options\nAs 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.\n\n### dataTransform\n**default: true**\n\nBy 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.\n\nYou can disable this behavior by setting `dataTransform` to false:\n\n```javascript\nconst api = new RailsRanger({ dataTransform: false })\n```\n\n---\n### axios\n**default: {}**\n\nAny object passed to the `axios` option will be handled to **Axios**.\nHere an example using the `baseUrl` configuration of Axios:\n\n```javascript\nconst api = new RailsRanger({ axios: { baseUrl: 'http://myapp.com/api/v1' } })\n\napi.list('users')\n// =\u003e GET request to http://myapp.com/api/users\n```\n\n#### See more configuration options in the [Axios documentation](https://github.com/mzabriskie/axios#request-config)\n\u003cbr\u003e\n\n## Use Rails Ranger just for path building\nYou 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:\n\n```javascript\nimport { RouteBuilder } from RailsRanger\nconst routes = new RouteBuilder\n\nroutes.create('users', { name: 'John' })\n// =\u003e { path: '/users', params: { name: 'John' }, method: 'post' }\n\nroutes.show('users', { id: 1, hidePassword: true })\n// =\u003e { path: '/users/1?hide_password=true', params: {}, method: 'get' }\n\nroutes.get('/:api/documentation', { api: 'v1', page: 3 })\n// =\u003e { path: 'v1/documentation?page=3', params: {}, method: 'get' }\n```\n\u003cbr\u003e\n\n## Nested resources\nYou can access your nested resources by using the `.resource` function:\n\n```javascript\napi.resource('users').list('blogPosts')\n//=\u003e GET request to /users/blog_posts\n\n\napi.resource('users', 1).list('blogPosts')\n//=\u003e GET request to /users/1/blog_posts\n```\n\u003cbr\u003e\n\n## Namespaced routes\nThe `.namespace` function can help you to build a path nested within a Rails namespace:\n\n```javascript\napi.namespace('users').list('blogPosts')\n//=\u003e GET request to /users/blog_posts\n\n\napi.namespace('admin_roles/:type', { type: 1 }).list('blogPosts')\n//=\u003e GET request to /admin_roles/1/blog_posts\n```\n\u003cbr\u003e\n\n## Available actions\n\n### List/Index\n```javascript\napi.list('users', { limit: 3 })\n// =\u003e GET request to /users?limit=3\n\napi.index('users', { limit: 3 })\n// =\u003e GET request to /users?limit=3\n```\n\n### Show\n```javascript\napi.show('users', { id: 1 })\n// =\u003e GET request to /users/1\n```\n\n### New\n```javascript\napi.new('users')\n// =\u003e GET request to /users/new\n```\n\n### Create\n```javascript\napi.create('users', { email: 'john@doe.com' })\n// =\u003e POST request to /users\n```\n\n### Edit\n```javascript\napi.edit('users', { id: 1 })\n// =\u003e GET request to /users/1/edit\n```\n\n### Update\n```javascript\napi.update('users', { id: 1, name: 'John Doe' })\n// =\u003e PATCH request to /users/1\n```\n\n### Destroy\n```javascript\napi.destroy('users', { id: 1 })\n// =\u003e DELETE request to /users/1\n```\n\u003cbr\u003e\n\n## Available HTTP methods\n\n### GET\n```javascript\napi.get('users/:id', { id: 1, hidePassword: true })\n// =\u003e GET request to users/1\u0026hide_password=true\n```\n\n### POST\n```javascript\napi.post('users/:id', { id: 1, name: 'John' })\n// =\u003e POST request to users/1 with a JSON payload containing: { \"name\": \"John\" }\n```\n\n### PATCH\n```javascript\napi.patch('users/:id', { id: 1, name: 'John' })\n// =\u003e PATCH request to users/1 with a JSON payload containing: { \"name\": \"John\" }\n```\n\n### PUT\n```javascript\napi.put('users/:id', { id: 1, name: 'John' })\n// =\u003e PUT request to users/1 with a JSON payload containing: { \"name\": \"John\" }\n```\n\n### DELETE\n```javascript\napi.delete('users/:id', { id: 1, hidePassword: true })\n// =\u003e DELETE request to users/1\u0026hide_password=true\n```\n\u003cbr\u003e\n\n## Request Cancellation\nSince rails-ranger is built on top of Axios, [request cancellation works the same way](https://github.com/axios/axios#cancellation).\n```javascript\nimport api from 'api-client'\n\nimport axios from 'axios';\nconst CancelToken = axios.CancelToken;\nconst source = CancelToken.source();\n\nconst request = api.get('/users/:id', {id: 1}, {cancelToken: source.token})\nrequest.cancel = (optionalMessage) =\u003e source.cancel(optionalMessage);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvictor-am%2Frails-ranger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvictor-am%2Frails-ranger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvictor-am%2Frails-ranger/lists"}