README.md

OliveBranch

This gem lets your API users pass in and receive camelCased or dash-cased keys, while your Rails app receives and produces snake_cased ones.

Install

1. Add this to your Gemfile and then bundle install:

gem "olive_branch"

2. Add this to config/applcation.rb if you want the clients to control the transformation behaviour through the Key-Inflection HTTP header sent by the client:

config.middleware.use OliveBranch::Middleware

Alternative, if you want to always convert between snake_case and camelCase for your API and only your API, to keep Rubyist and JavaScript developer's happy, use the following configuration:

excluded_routes = ->(env) { !env["PATH_INFO"].match(%r{^/api}) }
config.middleware.use OliveBranch::Middleware,
                      inflection:       "camel",
                      exclude_params:   excluded_routes,
                      exclude_response: excluded_routes

in your config/application.rb.

Use

Include a Key-Inflection header with values of camel, dash, snake or pascal in your JSON API requests.

For more examples, see our blog post.

Optimizations and configuration

OliveBranch uses multi_json, which will automatically choose the fastest available JSON parsing library present in your application. Most Ruby applications default to using the JSON library that ships with Ruby. However, by including a coder that multi_json considers faster, like Oj in your gemfile, you can potentially save up to ~20% response time.

The middleware can be initialized with custom camelize/dasherize implementations, so if you know you have a fixed size set of keys, you can save a considerable amount of time by providing a custom camelize that caches like so:

class FastCamel
  def self.camel_cache
    @camel_cache ||= {}
  end

  def self.camelize(string)
    camel_cache[string] ||= string.underscore.camelize(:lower)
  end
end


...

config.middleware.use OliveBranch::Middleware, camelize: FastCamel.method(:camelize)

Default inflection header key can be changed like

config.middleware.use OliveBranch::Middleware, inflection_header: 'Inflect-With'

A default inflection can be specified so you don't have to include the Key-Inflection header on every request. If you opt for default inflection, you may want to exclude the routes that Rails uses (see Filtering).

config.middleware.use OliveBranch::Middleware, inflection: 'camel'

A benchmark of this compared to the standard implementation shows a saving of ~75% rails response times for a complex response payload, or a ~400% improvement, but there is a risk of memory usage ballooning if you have dynamic keys. You can make this method as complex as required, but keep in mind that it will end up being called a lot in a busy app, so it's worth thinking about how to do what you need in the fastest manner possible.

Filtering

Content type

It is also possible to include a custom content type check in the same manner

config.middleware.use OliveBranch::Middleware, content_type_check: -> (content_type) {
  content_type == "my/content-type"
}

Excluding URLs

Additionally you can define a custom check by passing a proc

For params transforming

config.middleware.use OliveBranch::Middleware, exclude_params: -> (env) {
  env['PATH_INFO'].match(/^\/do_not_transform/)
}

Or response transforming

config.middleware.use OliveBranch::Middleware, exclude_response: -> (env) {
  env['PATH_INFO'].match(/^\/do_not_transform/)
}

Rails routes & Action Text

If you're using default inflection, exclude the routes that Rails uses

rails_routes = -> (env) { env['PATH_INFO'].match(/^\/rails/) }
config.middleware.use OliveBranch::Middleware, inflection: "camel", exclude_params: rails_routes, exclude_response: rails_routes

Upgrading to version 3

Default inflection header changed from X-Key-Inflection to Key-Inflection.

Troubleshooting

We've seen folks raise issues that inbound transformations are not taking place. This is often due to the fact that OliveBranch, by default, is only transforming keys when a request's Content-Type is application/json.

Note that your HTTP client library may suppress even a manually specified Content-Type header if the request body is empty (e.g. Axios does this). This is a common gotcha for GET requests, the body of which are often expected to be empty for reasons of caching. If you're seeing the middleware perform on POST or PATCH requests, but not GET requests, this may be your issue.

You may choose to force inbound transformation on every request by overriding the content_type_check functionality:

config.middleware.use OliveBranch::Middleware, content_type_check: -> (content_type) { true }

---

OliveBranch is released under the MIT License. See MIT-LICENSE for further details.

---

Visit code.viget.com to see more projects from Viget.