Radriar

A set of opinionated API design helpers for Ruby.

Add this line to your application's Gemfile:

gem 'radriar'

• 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.

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).

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

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"
  },
}

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": "..."
}

TODO: Redact

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
}

• Check TODO.md
• Discuss & implement new adapters:
  • Active Model Serializers
  • Grape::Entity
• Discuss & implement new hypermedia formats:
  • Collection+JSON
  • Siren

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