Designing a Hypermedia API with Grape & Roar Draft Hidden Sticky

Posted Wednesday, 05 November 2014 | Post Comment |

Slides from my talk last night @ API Craft NYC:

Code from walkthrough:

A more complete example:

Screenshot 2014-11-05 07.16.23


Video: Mentoring Engineers and Humans Draft Hidden Sticky

Posted Tuesday, 07 October 2014 | Post Comment |

My QCon 2014 talk Mentoring Engineers and Humans.

Screenshot 2014-10-07 08.10.31


I Want to Contribute to Open-Source: Where do I Begin? Draft Hidden Sticky

Posted Monday, 29 September 2014 | Post Comment |

I get this question a lot. I turned to my friends, HN and Twitter for some advice.

Step 1: Start by using open-source.

This is great advice. Before writing anything in your application, see if there’s an open-source implementation for it out there. This will make your code simpler, cleaner and more maintainable, or at least will expose you to the incredible amount of software written by very smart people out there.

Step 2: Start by fixing typos in someone else’s README.

The hardest part in contributing to open-source is making the initial effort. See a typo? Fork the repo, fix it, make a pull request. This exercises the contributing workflow and creates muscle memory.

Screenshot 2014-09-29 06.24.44

Step 3: Extract non-business logic from your application into a library.

Your application could be less bloated with utility code.

For example, pick a file from the lib folder in your Ruby project and extract it into a gem. I’ve done it numerous times with ruby-enum (Ruby), ARTiledImageView (Objective-C) or  VMWareTasks (C#).

Step 4: Don’t bloat your application with non-business logic.

Your application is bloated enough. Don’t add anything that’s not application-specific to it.

That utility class you’re about to write? Don’t do it. Make it into an open-source library right away. It seems like more work, but think about it - you’re starting very small, so the test-code-rinse-and-repeat loop is really tight, you’ll be saving time. Code will be more focused and have better interfaces, helping others on your team use it. You’ll have to document what you’re doing, saving future effort and helping your coworkers and maybe even other users of your library.

Other Resources

There’re other resources, groups, meet-ups and websites that help you find an open-source project to contribute to. These are all great! Please link to them in the comments.


Taking Over Someone Else’s Open-Source Projects Draft Hidden Sticky

Posted Friday, 19 September 2014 | Post Comment |
Thanks to the amazing crowd at GoGoRuCo 2014, San Francisco!

Screenshot 2014-09-19 20.33.18



Syntax Highlighting in Markdown Content with Recarpet, Coderay and Rails Draft Hidden Sticky

Posted Sunday, 31 August 2014 | Post Comment |

I wanted Ruby and JSON code blocks ala Github’s Flavored Markdown when rendering markdown documents in doppler. The idea is that we can API documentation authored in markdown, and rendered within a Rails application.

The first, harder part, is doing markdown rendering with syntax  highlighting. You render markdown with your favorite markdown gem (eg. Redcarpet), then parse the document and replace all code divs with a syntax highlighted version produced by Coderay. I had to also do some div swapping to avoid nested <pre> and <code> blocks.

  1. require 'redcarpet'
  2. require 'coderay'
  3. module MarkdownHelper
  4.   def render_markdown(text)
  5.     renderer =, fenced_code_blocks: true)
  6.     doc = Nokogiri::HTML::DocumentFragment.parse(renderer.render(text))
  7.     doc.css('code[@class]').each do |code|
  8.       div = CodeRay.scan(code.text.rstrip, code[:class].to_sym).div
  9.       code = code.replace(div)
  10.       code.first.parent.swap(code.first)
  11.     end
  12.     doc.to_s
  13.   end
  14. end

We can use this in a controller, assuming content lives in app/voews/content. Bonus: caching.

  1. class PagesController < ApplicationController
  2.   include MarkdownHelper
  4.   def show
  5.     fail 'Invalid Id' unless params[:id] =~ /^[\w\/]*$/
  6.     filename = Rails.root.join("app/views/content/#{params[:id]}.md")
  7.     @content = Rails.cache.fetch "content/#{params[:id]}/#{File.mtime(filename)}" do
  8.       text =
  9.       render_markdown text
  10.     end
  11.   end
  12. end

The corresponding view in pages/show.html.haml is as follows.

  1. %div
  2.   != @content

You can route to one of those pages in routes.rb.

  1. get '/terms', to: 'pages#show', id: 'terms'

See for a complete pull request with the above.

And here’s a screenshot of a rendered page.



The Other Side of Your Interview Draft Hidden Sticky

Posted Tuesday, 19 August 2014 | Post Comment |

I gave a talk yesterday at the Flatiron School about the interviewing and hiring process for Engineers at Artsy and beyond. This focuses primarily on explaining to juniors, ie. engineers who are about to enter the tech job market and has some useful elements for career changers.

Video from the talk:

Screenshot 2014-08-19 14.02.00


Golden Gate Ruby Conference 2014 Draft Hidden Sticky

Posted Friday, 18 July 2014 | Post Comment |

I’m very excited to be speaking at GoGaRuCo in San Francisco in September about taking over open-source projects, along with people like @wycats, @ultrasaurus and @pat. No pressure.

I want to hear about your experiences about taking over someone else’s open-source work! Email me at dblock[at]dblock[dot]org.



Serving Hypermedia with a Grape API and Roar Draft Hidden Sticky

Posted Friday, 18 July 2014 | Post Comment |

I’ve begun experimenting with Hypermedia APIs a bit more seriously, trying to come up with a good infrastructure for the next version of the Artsy API. It might even be a public one, but I am not making any promises right now. I’ve played with serialization and attempted to use ActiveModel::Serializers with the grape-activemodel_serializers gem and HAL with Roar. It turned out that we do need a little bit of help with Roar, so I released a new gem called grape-roar, which enables using Grape’s present keyword.

Check out an example application deployed at, source code in

First, swap the JSON formatter for Grape::Formatter::Roar. It’s implementation is almost identical to the default JSON formatter, except that it passes env along to the to_json call.

  1. module Acme
  2.   module Api
  3.     class RootEndpoint < Grape::API
  4.       prefix 'api'
  5.       format :json
  6.       formatter :json, Grape::Formatter::Roar
  7.     end
  8.   end
  9. end

Implement a presenter. It will typically have a number of :properties. Include Grape::Roar::Representer to use present in your API.

  1. module Acme
  2.   module Api
  3.     module Presenters
  4.       module SplinePresenter
  5.         include Roar::Representer::JSON::HAL
  6.         include Roar::Representer::Feature::Hypermedia
  7.         include Grape::Roar::Representer
  9.         property :uuid
  10.         property :reticulated
  12.         link :self do |opts|
  13.           request =[:env])
  14.           "#{request.base_url}/api/splines/#{uuid}"
  15.         end
  16.       end
  17.     end
  18.   end
  19. end

You can now present an entity in your API implementation.

  1. module Acme
  2.   module Api
  3.     class SplinesEndpoint < Grape::API
  4.       namespace :splines do
  5.         desc 'Get a spline.'
  6.         params do
  7.           requires :id, type: String, desc: 'Spline id.'
  8.         end
  9.         get ':id' do
  10.           spline = Acme::Models::Spline.find(params[:id])
  11.           present spline, with: Acme::Api::Presenters::SplinePresenter
  12.         end
  13.       end
  14.     end
  15.   end
  16. end

Click here to see the above code in action.

Representing collections is similar, check out for a complete example with bonus pagination support.

I’d love it if someone could contribute a POST/PUT example.


Swissnex: Swiss Startup Lunch Draft Hidden Sticky

Posted Monday, 23 June 2014 | Post Comment |

I had the pleasure and privilege of talking about my startup experiences in Switzerland in the 90s and more recently at Artsy in New York at a lunch organized by Swissnex. The amount of companies solving real problems in that room was quite impressive, ranging from biotech to robotics. Not a single social network, mostly serious entrepreneurs, the real deal. I talked mostly about people, including a reference to T-Shaped skills.



Anatomy of a Ruby Gem: Grape Draft Hidden Sticky

Posted Monday, 23 June 2014 | Post Comment |

I’ve recorded a screencast during the Anatomy of a Ruby Gem meetup in New York. It’s a deep dive into Grape internals.

Screenshot 2014-06-23 10.33.03

There was also someone who recorded a video of the talk, but it may be a bit hard to read.

< | 1  2  3  4  5  6  7  8  9  10  11  ... >