CamelCase Your Rails JSON API With OliveBranch

Eli Fatsi, Former Development Director

Article Categories: #Code, #Front-end Engineering, #Back-end Engineering

Posted on

Automatically convert the keys of your JSON API to play nicely with everyone's language of choice.

The Problem #

Client Side Applications backed by a JSON-producing Rails API are all the rage these days. Here at Viget we've worked on our fair share and frequently ran into this situation:

Front End Developer: So I'll POST JSON data to the API when someone submits a form, and you'll send back the response in JSON as well.

Back End Developer: Sounds great.

...one day later...

Back End Developer: I noticed that you're making API posts with camelCased keys, which doesn't jive too well with the Ruby backend, life would be better if you could convert all your JSON keys to be underscored when you make API calls.

Front End Developer: Well, actually, I noticed the API is serving up JSON with underscored keys, which is annoying to work with and looks bad in my camelCased JavaScript land. How about you convert all your JSON to use camelCase keys before you send it up?

Kind of similar to something I've recently learned is called a Cross Counter:

two people punching each other in the face at the same time Photo credit: http://tvtropes.org/pmwiki/pmwiki.php/Main/CrossCounter

The Solution #

Introducing OliveBranch. Extend an offer of peace to your better development half by letting OliveBranch handle the transformation of JSON keys.

By adding OliveBranch to your Rails middleware stack, a client can simply add a X-Key-Inflection header when making requests. OliveBranch will convert all incoming JSON keys to be underscore cased, and as the response is heading out the door, OliveBranch will modify the response keys based on the value of the X-Key-Inflection header (supports dash and camel currently).

Example #

POST the following data with the header X-Key-Inflection: camel:

{
  blogPost: {
    title: "Introducing OliveBranch",
    authorName: "Eli Fatsi",
    publishDate: "2016-04-20"
  }
}

OliveBranch will step in here, recognize the header and transform it into the following before passing the request in to the app for handling:

{
  blog_post: {
    title: "Introducing OliveBranch",
    author_name: "Eli Fatsi",
    publish_date: "2016-04-20"
  }
}

Let's say the app takes this data, creates the Blog Post, adds a "special_token" attribute, and returns the object as JSON back. OliveBranch will step in again to format the response before it's sent to the client:

{
  success: true,
  blogPost: {
    id: 42,
    title: "Introducing OliveBranch",
    authorName: "Eli Fatsi",
    publishDate: "2016-04-20",
    specialToken: "P94QH83HP"
  }
}

Everyone gets to work with the case that's common to their language, no one gets punched in the face.

We've had success using OliveBranch on our two latest Rails-API React-based client side apps, pow wow and TalkBackFM.

Installation, Setup, and Usage instructions can be found in the project's Github README. We hope OliveBranch brings peace to your teams as it has to ours.

Related Articles