Quickly reduce the amount of data your node API returns #

When designing an API, it’s easy to forget that not everyone has a cable modem. What if a client could easily request exactly the data it needed. That is what JSON Mask aims to do.

This is a tiny language and an engine for selecting specific parts of a JS object, hiding/masking the rest.

A code example helps to demonstrate how this works.

var mask = require('json-mask')
mask({p: {a: 1, b: 2}, z: 1}, 'p/a,z')  // {p: {a: 1}, z: 1}

JSON Mask seems like an interesting way to reduce the amount of data we send down the pipes.

Generate 4 language bindings for your API in one Go #

You just built an API, and want to make sure everyone can use it. Building libraries in every language isn’t only going to be hard, its going to take a lot of time. Time you don’t have. This is where Alpaca can help.

You define your API according to the format, alpaca builds the API libraries along with their documentation. All you have to do is publishing them to their respective package managers.

Right now it can generate API clients in PHP, Python, Ruby, and JavaScript. You can see examples of the generated client libraries here. I can’t speak to the quality of all the generated language bindings, but I took a cursory look at the Python lib and it looks good. Looks like Alpaca could save us all a lot of time.

Thumbor is a self hosted thumbnail-as-a-service #

Thumbor is pretty impressive. Not only does it take something like thumbnailing, which is always painful, and makes it easy. It has cool image operation out of the box.

It also features a VERY smart detection of important points in the image for better cropping and resizing, using state-of-the-art face and feature detection algorithms

It even sports an east to use API with urls like:

http://<thumbor-server>/300x200/smart/<image-url>

If you’re like me and think thumbnailing is a pain, checkout Thumbor.

Give any SQL database a REST interface with Sandman #

Let’s say you have a SQL database. You might wish it had a REST interface and a nice admin UI. That used to mean writing a bunch of code but now with Sandman it’s a one liner.

Zero boilerplate code is required. In fact, using sandmanctl, no code is required at all. Your existing database structure and schema is introspected and your database tables magically get a RESTful API and admin interface.

Sandman was created by Jeff Knupp and can be used with any database that SQLAlchemy supports.

Prototype JSON APIs with Fortune.js #

If you hadn’t heard, JSON API is a format for building awesome APIs on top of JSON. You can see other posts tagged with JSON API here.

Recently, a new project related to JSON API was released: Fortune.js.

Fortune.js, a web framework for prototyping rich hypermedia APIs, allows you to rapidly prototype the server side of any JSON API api.

Check it out:

var fortune = require('fortune') 
  , app = fortune({ 
    db: 'petstore' 
  }) 
  .resource('person', { 
    name: String, 
    age: Number, 
    pets: ['pet'] // "has many" relationship to pets 
  }) 
  .resource('pet', { 
    name: String, 
    age: Number, 
    owner: 'person' // "belongs to" relationship to a person 
  })
  .listen(1337);

This will give you all the proper routes and format the responses in the right way to conform with the spec.

If you didn’t guess, fortune.js makes heavy use of Node, so you can get it from npm:

$ npm install fortune

I am super pumped about projects like this, because it shows off the great benefits of standardizing around a type like JSON API. Tooling that knows how to handle the type makes it really easy to get off the ground.

JSON API now has a MIME type #

If you hadn’t heard, JSON API is a format that myself and Yehuda Katz have been persuing to help standardize APIs. It came out of the work done on ember-data and active_model_serializers.

We’ve been tweaking the format after receiving feedback from many people, and both the exemplar implementations as well as a variety of other implementations have made it pretty easy to use our format.

Here’s the news, though: we’re one step further along the standardization process.

Recently, the IANA approved our application for a media type designation for JSON API. This means you can officially serve your APIs with the type application/vnd.api+json. Neat!

#97: API wrappers, Ruby and open source with Drew Blas

Adam Stacoviak and Andrew Thorp talk with Drew Blas of Chargify about API wrappers, Ruby, open source, and more. You can tune-in LIVE on Tuesday’s at 5pm CST. Drew Blas – Explorer « The life and code of a passionate developer drewblas (Drew Blas) on GitHub drewblas (drewblas) on Twitter drewblas/consignment chargify (Chargify) chargify/chargify2 chargify/doculab

Snaphax – creative freedom or unlawful code? #

Yesterday, on HackerNews, Thomas Lackner asked the question if he should remove the library he created to consume the Snapchat ‘API,’ upon request from Snapchat themselves. From Snapchat:

Hi Thomas, I’m writing to ask that you remove Snaphax from github and no longer publish or distribute it. Snapchat does not permit third party software to access our API and we consider Snaphax to be an unlawful circumvention device under 17 U.S.C. § 1201(a)(1).

This sparked a lot of debate and coverage. It brings up a good question, and one we would love to discuss on twitter: Is this an ethical use of a publicly available service or not?

You can see the snaphax code on GitHub, read the article on venturebeat and checkout the thread on HackerNews to get the backstory.

Let us know what you think!

flickr-store, store arbitrary data with your 1TB Flickr cloud #

A neat hack from Ryan LeFevre on Flickr’s API.

From the readme:

Store arbitrary data with your 1TB Flickr cloud drive by encoding any file as a PNG. This is mostly a proof of concept right now. Don’t do anything beyond tinkering with it yet.

Check out the project on GitHub!


Thanks to Sam Soffes for the tip!

Hyperresource: a hypermedia API client for Ruby #

Any of you who know me aren’t surprised about me posting this story: it’s right up my alley!

Basically, hyperresource is intended to be a general hypermedia client. What’s that mean? It can work with any API that happens to use one of the media types it supports. Right now, that’s just HAL+JSON, but more will be added in the future.

What’s that mean in terms of code? Well, here’s an example from the README:

api = HyperResource.new(root: 'https://api.example.com')
# => #<HyperResource:0xABCD1234 @root="https://api.example.com" @href="" @namespace=nil ... >
root = api.get
# => #<HyperResource:0xABCD1234 @root="https://api.example.com" @href="" @namespace=nil ... >
root.response_body
# => { 'message' => 'Welcome to the Example.com API',
#      'version' => 1,
#      '_links' => {
#        'self' => {'href' => '/'},
#        'users' => {'href' => '/users{?email,last_name}', 'templated' => true},
#        'forums' => {'href' => '/forums{?title}', 'templated' => true}
#      }
#    }
jdoe_user = api.users.where(email: "jdoe@example.com").first
# => #<HyperResource:0x12312312 ...>

How does it know how to look up those users? Well, there’s a users link relation on in the response, and it has a templated URI as its href attribute. This lets the client reflect and know how to look up users by their email or last name.

The power of this generic tooling is that we no longer have to think about how to parse HAL, how to interpret the response… we have this one library which works with any HAL-powered API.

The biggest drawback of hyperresource is that it’s read-only at the moment, nothing but GET. But it shows a lot of promise, and I’m excited to see this kind of stuff pop up in the wild. Everything I see points to 2013 as the year of example code for hypermedia services.

Check it out on GitHub.

Write Ruby API’s with Stripe’s Poncho (a DSL for REST interfaces) #

As we said in a previous post: WE LOVE STRIPE!

The team at Stripe has open sourced a RubyGem that makes REST API’s easy to create, Poncho. It’s compatible with any rack-based framework — like Rails or Sinatra. Best of all, it has a slew of (simple to use) features:

Installation is simple, just install the poncho gem (or add gem poncho to your Gemfile). After installation, you can setup your API:

class ChargeResource < Poncho::Resource
  param :amount, :type => :integer
end

class ChargeCreateMethod < Poncho::JSONMethod
  param :amount, :type => :integer, :required => true

  def invoke
    charge = Charge.new
    charge.amount = param(:amount)
    charge.save

    ChargeResource.new(charge)
  end
end

post '/charges', &ChargeCreateMethod

The above code, which was pulled from the documentation is using Sinatra, but you could easily swap Rails out:

match '/charges' => ChargeCreateMethod, :via => :post

The documentation is thorough, and does a great job at explaining how to use Poncho. You can also view the source or discuss this on HackerNews.

The White House shares their web API standards on GitHub #

A fine hat tip to Lisa Nelson for sharing this on Twitter.

From the readme:

This document provides guidelines and examples for White House Web APIs, encouraging consistency, maintainability, and best practices across applications. White House APIs aim to balance a truly RESTful API interface with a positive developer experience (DX).

We’re certainly fans of open government around here. This makes us smile.

What do you think? Discuss on Hacker News.

Tumblr releases their SDK for iOS (and other official client libraries for their API) #

Bryan Irace, iOS developer at Tumblr, announced in this post that Tumblr recently open-sourced their SDK for iOS as well as a few official client libraries for the Tumblr API.

We’ve been using this SDK in production for quite some time now and are thrilled to finally be able to share it with you.

If you’re interested in integrating with Tumblr on iOS or OS X in a way that the SDK doesn’t currently facilitate, please get in touch. I’m very interested in hearing any and all feedback on how we can make this as easy as possible.

Keep an eye on Tumblr’s org on GitHub if you’re looking to integrate with the Tumblr API.

GitHub exposes public ssh keys for its users #

Thanks for sharing this Postmodern.

Today I learned from @postmodern_mod3 that GitHub exposes public ssh keys for its users. For example, if you wanted my public keys: https://github.com/adamstac.keys

So never again should you have to ask, “What’s your public ssh key?” You can just curl -O https://github.com/<username>.keys their public keys from GitHub and move on.

Although, Rick’s response to that tweet was to not use that method and to use their API to list public keys for a user instead.

Discuss the pros and cons of this on Hacker News.

Work with 1.8 million IRS-recognized Nonprofits in Ruby with the GuideStar API #

For those out there working on fighting social injustices and changing the world like we are at Pure Charity, I wanted to mention this Ruby wrapper for the Guidestar API from Mauricio Gomes of Gemini SBS.

We’re making use of it :)

For example, we can…

Search by organization name:

Guidestar::Client.search(:name => "Help One Now")

Search by EIN:

Guidestar::Client.search(:ein => "26-3618295")

and more

From the about page:

If you care about nonprofits and the work they do, then you’re affected by what GuideStar does. We gather and publicize information about nonprofit organizations. Our reach is far and wide. Our database is broad and deep. We encourage nonprofits to share information about their organizations openly and completely.

If you’re new to GuideStar, you can search and find the nonprofit information you need (or integrate with their API) – and it’s free.

Check out the source on GitHub or create your account to get started.

UPDATE: It turns out that access to the web search is free, but API access is not free. Bummer. Personally, I think a free limited API would be a smart choice for GuideStar.

Hyperspider – Declarative HATEOAS API crawler for Node.js #

Interesting project from Jed Schmidt to roll up resources in hypertext APIs:

Give it a list of url patterns, and it will recursively crawl your hypertext HTTP API, streaming back every matching endpoint.

var hyperspider = require("hyperspider")

var options = {
  host: "mytwitterclone.biz",
  path: [
    "/users/jed",
    "/users/jed/following",
    "/users/*"
  ]
})

hyperspider(options, function(err, data) {
  // data is an array with the result entities of 6 endpoints:
  // 1. /users/jedschmidt
  // 2. /users/jedschmidt/following
  // 3. /users/janl
  // 4. /users/cramforce
  // 5. /users/hblank
  // 6. /users/theophani
})

Source on GitHub.

Backstop – Simple HTTP service for submitting metrics to Graphite #

We’ve mentioned a couple of Graphite-related projects previously. Jason Dixon and Michael Gorsuch from Heroku have released Backstop, a simple HTTP-to-Graphite proxy to make it simple to send metrics. Using the /publish method, metrics and annotations can be posted that match any approved prefixes found in the PREFIXES environment variable, custom in the following example:

# Send a metric
RestClient.post("https://backstop.example.com/publish/custom",
   [{:metric => key, :value => value, :measure_time => Time.now.to_i}].to_json)

# Send an annotation
RestClient.post("https://backstop.example.com/publish/note",
   [{:metric => "foobar.release", :value => "v214", :measure_time => Time.now.to_i}].to_json)

Check the README for local usage and instructions for deploying to Heroku.

#81: Celluloid, concurrency, and more with Tony Arcieri

Wynn talked with Tony Arcieri, creator of Celluloid, about concurrency in Ruby and his thoughts on Erlang, Clojure, and design patterns. Items mentioned in the show Tony Arcieri, creator of Celluloid. Celluloid is painless multithreaded programming for Ruby. Celluloid:IO provides evented I/O for Celluloid actors. DCell lets you build distributed Celluloid apps over 0MQ. Adam […]

Rails::API – Lightweight Rails stack for headless API apps #

“Rails is just an API,” say Alex (featured on Episode 0.7.1) and others. Rails core team member Santiago Pastorino might not endorse the “just” part, but his Rails::API aims to provide a slimmer stack for those wanting to use Rails as an API backend for their client-side or mobile applications. The result is a fine-tuned subset of Rails, letting the developer opt-in to just the middleware needed. Rails::API requires a small change to your controllers:

# instead of
class ApplicationController < ActionController::Base
end

# do
class ApplicationController < ActionController::API
end

Check out the README for installation and advanced usage and Santiago’s blog post for more.

We’ll be covering a similar project, Lightrail, when we chat with Tony Arcieri about Celluloid next week.

MBRequest – Easier API wrappers in iOS and OSX #

A good API wrapper should handle network transport, payload serialization/deserialization, and authentication, abstracting these details away in order to let the developer deal with the business domain of the API. Projects like Faraday, Requests, and others have made creating higher level wrappers much easier.

MBRequest from Mobiata does the same for iOS and OSX:

NSURL *url = [NSURL URLWithString:@"https://gdata.youtube.com/feeds/api/standardfeeds/top_rated?alt=json?time=this_week"];
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:url];
[urlRequest setValue:@"gzip" forHTTPHeaderField:@"Accept-Encoding"];
MBJSONRequest *jsonRequest = [[[MBJSONRequest alloc] init] autorelease];
[jsonRequest performJSONRequest:urlRequest completionHandler:^(id responseJSON, NSError *error) {
    if (error != nil)
    {
        NSLog(@"Error requesting top-rated videos: %@", error);
    }
    else
    {
        NSArray *videos = [[responseJSON objectForKey:@"feed"] objectForKey:@"entry"];
        for (NSDictionary *videoInfo in videos)
        {
            NSString *title = [[videoInfo objectForKey:@"title"] objectForKey:@"$t"];
            NSString *author = [[[[videoInfo objectForKey:@"author"] objectAtIndex:0] objectForKey:@"name"] objectForKey:@"$t"];
            NSLog(@"'%@' by %@", title, author);
        }
    }
}];

Check out the examples folder in the project source for implementation ideas.

GitHub Archive: API for GitHub’s historical timeline #

You folks create a lot of events on GitHub. Trying to mine and report on that data is definitely a big data problem. Ilya Grigorik wants to help the community get a handle on the GitHub firehose with GitHub Archive. With an API call you can get a range of GitHub’s public timeline data for all seventeen event types:

require 'open-uri'
require 'zlib'
require 'yajl'

gz = open('http://data.githubarchive.org/2012-03-11-12.json.gz')
js = Zlib::GzipReader.new(gz).read

Yajl::Parser.parse(js) do |event|
  print event
end

The source is on GitHub. Be sure and listen to Ilya on Episode 0.5.5 talking about Goliah, EventMachine, and SPDY.