Opinionated API design and implementation helpers for Ruby web APIs
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib
spec
.gitignore
.rspec
.ruby-version
.travis.yml
Gemfile
LICENSE.txt
README.md
Rakefile
TODO.md
radriar.gemspec

README.md

Radriar

Gem Version Build Status Coverage Status Dependency Status Code Climate

A set of opinionated API design helpers for Ruby.

Installation

Add this line to your application's Gemfile:

gem 'radriar'

Conventions and included components

  • API based on Grape
  • Model representation with representable
  • Use of the represent and represent_each helpers inside the API, or a Grape formatter (coming soon).
  • Hypermedia features are based on HAL and require Roar.

Key Features

TODO: Redact

  • Key translation (Snake case to underscore and viceversa).
  • Optional field includes (Pass fields parameter in URL).
  • Conventional error responses.
  • Optional inclusion/exclusion of hypermedia (HAL).

Usage

Include the gem in your Gemfile:

gem 'radriar'

Then radriarize your API ;), aka invoke the #radriarize method with the specified options from your API definition.

class UserAPI < Grape::API
  radriarize representer_namespace: 'MyApp::Representers',
             hypermedia: true,
             translate_keys: true

Dynamic APIs

Assuming you're using the right conventions (to be redacted) this will magically turn your API from this:

{
  "id": "blackxored",
  "first_name": "Adrian",
  "last_name": "Perez",
  "avatar_url": "...",
  "hireable": false,
  "registered_at": "...",
  "social_urls": {
    "github":  "https://github.com/blackxored",
    "twitter": "https://twitter.com/blackxored"
  },
  "comments": [ /* ... */],
}

To this:

{
  "_links": {
    "self": {
      "href": "/users/blackxored"
    },
    "html": {
      "href": "/#/u/blackxored"
    },
    "timeline": {
      "href": "/users/blackxored/timeline"
    },
  },
  "_embedded": {
    "total": 2,
    "comments": [ /* ... */ ]
  },
  "id": "blackxored",
  "firstName": "Adrian",
  "lastName": "Perez",
  "avatarUrl": "...",
  "hireable": false,
  "registeredAt": "2013-06-18T06:37:39.248Z",
  "socialUrls": {
    "github":  "https://github.com/blackxored",
    "twitter": "https://twitter.com/blackxored"
  },
}

Partial Responses

You can request partial responses (ideal for mobile apps). Just hit any endpoint with an optional fields attribute.

(TODO: Check that key translation works at the partial response level)

From the response above:

curl $URL?fields=id,firstName,avatarUrl

Will return the following JSON document:

{
  "id": "blackxored"
  "firstName": "Adrian",
  "avatarUrl": "..."
}

Error Conventions

TODO: Redact

Pagination

TODO: Test and implement

All your collection get automated pagination by default. In the case of hypermedia APIs it also includes pagination links.

{
    "_links": {
        "self":  "/collection?page=3",
        "first": "/collection",
        "next":  "/collection?page=4"
        "prev":  "/collection?page=2",
        "last":  "/collection?page=10"
    },
    "_embedded": {
      "collection": [ /*...*/]
    },
    "total": 250,
    "per": 25
}

Contributing

Roadmap

Process

  1. Fork it ( https://github.com/blackxored/radriar/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request