Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/polakowski/resourcey
Lightweight utility for building simple resource-based JSON Apis
https://github.com/polakowski/resourcey
json-api rails ruby ruby-gem ruby-on-rails
Last synced: about 2 months ago
JSON representation
Lightweight utility for building simple resource-based JSON Apis
- Host: GitHub
- URL: https://github.com/polakowski/resourcey
- Owner: polakowski
- Created: 2018-02-16T10:54:13.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2018-09-04T14:32:57.000Z (over 6 years ago)
- Last Synced: 2024-10-25T12:58:56.004Z (2 months ago)
- Topics: json-api, rails, ruby, ruby-gem, ruby-on-rails
- Language: Ruby
- Homepage:
- Size: 73.2 KB
- Stars: 20
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Resourcey
  
A lightweight rails gem for building resource-based APIs. It gives you some conventions and convenient solutions for rendering resources in JSON format.
### Table of contents
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [Controller](#controller)
- [Serialization](#serialization)
- [How to fetch](#fetch-the-data)
- [Pagination](#pagination)
- [Filtering](#filtering)
- [Configuration](#configuration)
- [Contributing](#contributing)
## Requirements
Resourcey requires ruby 2.2.2 or higher.
## Installation
Add Resourcey to your `Gemfile`:
```ruby
gem 'resourcey'
```
And then:
```
bundle
```
Or install it manually:
```
gem install resourcey
```
## Usage
### Controller
For a resource called `user`, just create `UsersController`:
```ruby
class Api::V1::UsersController < Resourcey::Controller
end
```
For further reading, [click here](/docs/CONTROLLER.md).
### Serialization
Now you need a serializer, let's assume that `User` has an email and an ID, go with this:
```ruby
class UserSerializer < Resourcey::Serializer
attributes :id, :email
end
```
For further reading, [click here](/docs/SERIALIZER.md).
### Fetch the data
Don't forget to create a correct route in your `routes.rb` file, and you're good to go!
Now just visit `/api/v1/users`, and see how your resources are rendered.
```json
/* example response */
[
{ "id": 1, "email": "[email protected]" },
{ "id": 2, "email": "[email protected]" }
]
```
### Pagination
To paginate resources, simply invoke `paginate` method in controller, like this:
```ruby
class ResourcesController < Resourcey::Controller
paginate
end
```
This will use default `:paged` paginator. Now you need to pass `page` and `per_page` parameters in `pagination` parameter value, like this:
```
http://api.example.com/resources?page=3&per_page=10
```
This will fetch page 3, with 10 resources per single page. That's all! Pagination can be configured globally (see "Configuration" below). Also you can configure every controller's pagination.
For further reading, [click here](/docs/PAGINATION.md).
### Filtering
You can filter your resources using filter objects defined per single resource model. See below for an example:
```ruby
class UserFilter < Resourcey::Filter
filter :older_than do |value, scope|
scope.where('users.age > ?', value)
end
end
```
For further reading, [click here](/docs/FILTERING.md).
## Configuration
Create configuration file in your `config/initializers` folder, and configure as usual:
```ruby
Resourcey.configure do |config|
config.some_config_variable = :some_value
end
```
#### Available config variables
| **config var** | **description**| **default** |
| --- | --- | --- |
| `default_paginator` | Name of paginator that will be used in every controller, if not configured on controller-level. Click [here](/docs/PAGINATION.md) for details. | `:paged`
| `controller_parent` | Class or class name of controller, that `Resourcey::Controller` will inherit from. | `ActionController::Base` |
## Contributing
If you want to take part in developing resourcey, fork this repository, commit your code, and create pull request.
### Requirements
- ruby 2.2.2 or higher
- bundler gem
### Running local tests
- rspec