
As a sequel to my talk last year on [building Stripe's API], I thought it'd
be useful to go over how we scaled some of our internal abstractions to
continue building and iterating quickly. I gave this talk
at [APIStrat Chicago] a couple of weeks ago and several [events] at
[HeavyBit] last week, who generously recorded and transcribed the whole thing
for anyone who'd like to [watch a video]. (Thanks, HeavyBit!)

I'm the kind of person who will impatiently watch videos of talks or lectures on
2x speed and greatly prefer reading a blog post that can be skimmed easily, so I decided
to write an accompanying post to go with the slides.

Enjoy! (:

[APIStrat Chicago]: http://apistrategyconference.com
[building Stripe's API]: http://amberonrails.com/building-stripes-api
[events]: http://www.meetup.com/Move-Fast-and-Break-Things/
[HeavyBit]: https://heavybit.com
[watch a video]: http://www.heavybit.com/library/developer-technical/video/2014-09-30-amber-feng
[email]: mailto:amber@stripe.com
[Twitter]: https://twitter.com/amfeng

<div class="max-w-2xl mt-16 mb-16">
  <div style="left: 0; width: 100%; height: 0; position: relative; padding-bottom: 74.9296%;"><iframe src="https://speakerdeck.com/player/bfc6cae030830132ab4b06da7886ac56" style="border: 0; top: 0; left: 0; width: 100%; height: 100%; position: absolute;" allowfullscreen scrolling="no" allow="encrypted-media"></iframe></div>
</div>

## Let's build an API!

Stripe has [a lot of APIs], and as a result we had to quickly figure out how
to scale our abstractions and code. Since code is worth a thousand words
(that's a saying, right?), I'll run through an example of building an API.

Here's a super simple example of an API endpoint in [Sinatra] that
creates credit card charges:

```rb
post '/charges' do
  # Authentication
  api_key = get_api_key
  user = User.find_by_key(api_key)

  unless user
    return {error: "Invalid API key."}
  end

  # Collect user parameters
  card_number = params[:card_number]
  amount = params[:amount].to_i

  # Validations
  unless card_number.length == 16
    return {error: "Invalid card number."}
  end

  unless amount > 0 and amount <= CHARGE_MAX
    return {error: "Invalid amount."}
  end

  # Actually create the charge
  charge = create_charge(card_number, amount)

  # Return an API response
  json {
    id: charge.id,
    amount: charge.amount
    card_number: charge.redacted_card_number,
    success: charge.success
  }
end
```

It's starting to get a little crowded in here, but it's more or less a working
API. That was easy!™

[a lot of APIs]: https://stripe.com/docs/api
[Sinatra]: http://www.sinatrarb.com/

## What next?

As you start adding new endpoints, functionality, and changes you run into more
problems.

How do you (scalably) do things like authentication,
validation, actual API logic, error handling, authentication, and _at the
same time_ support every combination of behaviors that has ever existed in the
past? We can't ever break integrations&mdash;particularly as a
payments processor, broken
integrations means our users are literally losing money every minute. We need
to be able to build and change things rapidly without compromising any API stability or
backwards compatibility.

Once your API has reached a certain size, something that also starts to creep up
on you is dependencies. Documentation is a good example of this. Say you build
an API and write up docs in the form of static
HTML or markdown. It launches and everyone is happy.

A week later you decide to add something to the API. You diligently add it
to your API code and maybe even remember to make the change in the docs as
well.

With more additions or updates though, sooner or later this is going to
happen:

> Crap, I forgot to update the docs!
> &mdash; Everyone, ever

Sound familiar? (This has definitely happened to me more than once.) How did we
start making these problems less painful?

## Separate the layers of responsibility

In the example above, many things are going on at once: authentication, validation,
endpoint-specific logic, error handling, and constructing the response.

[Separation of responsibilities] is CS 101, so we started moving things out
and building abstractions around them.

For authentication and error handling, we use [Rack middleware] and it works
pretty well. You shouldn't have to worry about authenticating users in the
middle of your API logic (most frameworks have a concept of `before` filters
for this as well). You
also shouldn't have to hardcode error response formats. Wouldn't it be nice
if you could just throw an error and know that someone else will catch it to
format it into the proper response later?

```rb
use ErrorHandler
use Authenticator

get '/charges/:id' do
  user = env.user
  id = params[:id]

  if charge = user.get_charge(id)
    json {
      id: charge.id
      ...
    }
  else user.get_charge(id)
    raise UserError.new("No charge #{id}!")
  end
end
```

We represent endpoint validations, logic, and response generation internally in
our code as `APIMethod`s and `APIResource`s. If you're familiar
with [MVC], they're very similar to controllers and views for your API.

```rb
class ChargeCreateMethod < AbstractAPIMethod
  required :amount, :integer
  required :card_number, :string

  resource ChargeAPIResource

  def execute
    create_charge(amount, card_number)
  end
end

class ChargeAPIResource < AbstractAPIResource
  required :id, :string
  required :amount, :integer
  required :card_number, :string
  required :success, :boolean

  def describe_card_number
    charge.redacted_card_number
  end
end
```

[Separation of responsibilities]: http://en.wikipedia.org/wiki/Separation_of_concerns
[Rack middleware]: http://stackoverflow.com/questions/2256569/what-is-rack-middleware
[MVC]: http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller


## Make it really hard to mess up

A good UX design principle is that you should make it really hard for your
users to mess up or do the wrong thing. Why not apply this toward building the
API as well?

One thing that we did that I thought was really cool was a system for
documenting our API. To try to address "I forgot to update the docs!"
syndrome, we made it really hard to forget by putting the
documentation right under the code that adds a new property.

```rb
class ChargeCreateMethod < AbstractAPIMethod
  required :amount, :integer
  required :card_number, :string

  document :amount, "Amount, in cents."
  document :card_number, "The card number."

  ...
end
```

Our [documentation] then auto-generates itself from these specs&mdash;for
changing most things, there's no need to go dig up static HTML files.

Similarly for our [API libraries] (or at least those that can support it),
we don't hardcode properties for each object but instead [dynamically generate
them] based on the properties present in the response that is received.
This way we don't have to worry about adding new fields to object
definitions in each library.

[documentation]: https://stripe.com/docs/api
[API libraries]: https://github.com/stripe
[dynamically generate them]: https://github.com/stripe/stripe-ruby/blob/master/lib/stripe/stripe_object.rb#L32

## Hide your backwards compatibility

We're often asked how we implement our API backwards compatibility. This probably
merits an entire talk and post by itself, but I'll go over it at a high level.

When a user starts implementing Stripe for the first time they don't need to
worry about API versions. Instead it's invisible&mdash;they'll innocently make
their first API request, we'll record what
internal version they're on, and from then on our code takes care of making sure
we never break their integration.

If a user wants to worry about versions they can: we allow overrides to
be sent in [via request headers] and users can upgrade their version via the
dashboard. However most people won't care, so they shouldn't have to know about
it. All most Stripe users see is that their integration, even if they [first
wrote it years ago], never breaks.

All of our versions live in the same code base and are deployed to the same
service. We don't do separate services or deploys for different versions. The
downside of doing is that it's easy for things to get hairy after a
while.

[via request headers]: https://stripe.com/docs/api#versioning
[first wrote it years ago]: https://twitter.com/pippinsplugins/status/502553344138039296

### First pass

Imagine sometime down the road Stripe decides to deprecate the `amount`
parameter and all charges are now $1. (Disclaimer: I'm pretty sure we
will never actually do this.)

What's the naive way to implement that change in behavior? Maybe something like this:

```rb
def execute
  if !user.old_version? && params[:amount]
    raise UserError.new("Invalid param.")
  end

  ...

  if !user.old_version?
    response.delete(:amount)
  end
end
```

There are a couple of problems with this. First, who knows what `old_version?` is
supposed to mean? You can infer it from the code, but it's really not intuitive
and is just waiting for accidental regressions. Second, the regular API logic and
legacy logic are being mixed together. If someone wanted to add or update the something in
the current API (somewhere in that `...`), they would have to wade through
those extra conditionals.

### Gates

We've modeled our versioning system around a series of gates. A "gate" is a
database flag (similar to [feature flags]) that our code can use to determine
what functionality to allow. For example, if a user is on an old version and is
therefore allowed to send the `amount` parameter, they're on the `allows_amount`
gate.

We declare all of the versions along with the corresponding functionality gates
in a single YAML file:

```rb
-
  :version: 2014-09-24
  :new_gates:
    -
      :gate: allows_amount
      :description: >-
        Sending amount is now deprecated.
```            

and are able to decouple versions from the actual behavior they represent in
our code:

```rb
def execute
  if !user.gating(:allows_amount) && params[:amount]
    raise UserError.new("Invalid param.")
  end

  ...

  if !user.gating(:allows_amount)
    response.delete(:amount)
  end
end
```

To go one step further and actually get that logic out of the endpoint execution
code, separate compatibility layers were added to our code flow. Because who
doesn't need more layers of indirection?

![](/images/posts/move-fast-dont-break-your-api/compatibility-layers.png)

Now when a request comes in it first filters through the request
compatibility. That layer may or may not reject it based on the parameters (like
if someone passes in `amount` who isn't allowed to) or munge the parameters to
something that the later logic expects.

After the response is created, it passes through another layer of response
compatibility which transforms the response into whatever the user's version
dictates. The great thing about this is that the API logic and response
construction steps can represent the _current_ version of the API without any
legacy edge case clutter.

It's worth noting that these layers aren't free: there's a certain amount of
complexity added when fiddling with requests and responses that are passed through,
but we made the tradeoff to be able to keep our general API code (what engineers
spend 80-90% of their time working on) clean and easier to reason about.

[feature flags]: http://en.wikipedia.org/wiki/Feature_toggle

## In the real world

What does this look like in practice? Stripe has (at the time of writing) 106
endpoints, 65 versions, and 6 API client libraries. You can do the combination math
yourself.

We would be far behind where we are today if we couldn't find, read, and change
code quickly without being afraid of breaking our users.

## Conclusion

So design for yourself. Spend some effort not just thinking about how you can
optimize your users' experiences, but how you can optimize your own as well.

Stripe's far from perfect; we're learning more and more every day and
(like any other startup) there are still very
many things in our code that annoy and embarass us. I
hope this gives others a sense of things we've learned over the years
and helps other developer companies who are tackling the same problems.

If you're ever interested in chatting about any of these topics, I'd love to
chat&mdash;drop me an [email] or poke me on [Twitter].

I ended up writing far more than I had intended so if you made it down this
far, congratulations and thanks for reading!

_Credit to Sheena Pakanati, Saikat Chakrabarti, Ross Boucher, Greg Brockman, and many others at Stripe for contemplating, building, and iterating on everything covered in this post._


Move fast, don't break your API


I spend a lot of time nowadays doing code reviews and helping spin people up on
Stripe (or more generally, distributing knowledge about our code base). One
thing I found myself needing over and over again was the ability to show someone
a file or some code over IM or [Slack]. Since we use Github to host our
repositories, this is as easy as [linking to the online file].

However, it's pretty annoying to have to use Github's UI to navigate through
folders, and I almost always mess up trying to type the full path in the URL
(blob? tree?). I also use [Command-T] with Vim, which means I never remember
file paths or exact file names. (If you don't use Command-T or something
similar, you should&mdash;it's the single biggest improvement to my code 
reading/writing productivity over the last couple of years.)

"Wouldn't it be awesome if I could just open a file in Github directly from Vim 
with some keyboard shortcut?", I thought to myself.

I did a bunch of research to try to figure out how hard it would be to build 
myself (I've never written a Vim plugin before), and stumbled upon 
`git web--browse`. From the [man page]:

```
NAME
    git-web--browse - git helper script to launch a web browser

SYNOPSIS
    git web--browse [OPTIONS] URL/FILE ...

DESCRIPTION
    This script tries, as much as possible, to display the URLs and FILEs
    that are passed as arguments, as HTML pages in new tabs on an already
    opened web browser.
```

Sounds like exactly what I want!

Amazingly, [fugitive], a Git wrapper for Vim, actually has this functionality
built in. If you have fugitive installed already, try it right now: go to a file
that's hosted on Github, then type in the command `:Gbrowse`. It'll
automagically open the corresponding link (keeping in mind what branch you're
on, and everything) in your browser. You can even highlight a couple lines in
visual-mode to have those be highlighted on Github.

I ended up remapping `:Gbrowse`  in my `.vimrc` to something easier to type, 
you should too:

```
noremap <leader>w :Gbrowse<cr>
```

I use this at least a few times every single day. Hope you find it useful too!

[Slack]: https://slack.com/
[linking to the online file]: https://github.com/stripe/stripe-ruby/blob/master/lib/stripe/charge.rb#L7
[Command-T]: https://github.com/wincent/Command-T
[man page]: http://git-scm.com/docs/git-web--browse.html
[fugitive]: https://github.com/tpope/vim-fugitive



Opening files in Github from Vim


I just got back from New York, where I gave my first conference talk ever at the [API Strategy and Practice] conference. Pretty exciting!

I thought it would be interesting to talk about [Stripe]'s API, particularly lessons learned and what kind things we did to try to make using the API as easy as possible. I've included the slides below, but most of the content isn't on the slides so I'll try to cover some of the highlights below.

As a disclaimer, we definitely don't know everything. A lot of what you see on Stripe today is the product of thought and discussion, as well as a lot of trial and error. I hope you find something in here applicable toward your own API! (:

[API Strategy and Practice]: https://apistrategyconference.com
[Stripe]: https://stripe.com

<div class="max-w-2xl mt-16 mb-16">
  <div style="left: 0; width: 100%; height: 0; position: relative; padding-bottom: 74.9296%;"><iframe src="https://speakerdeck.com/player/c65f0040629c0130953122000a9d0218" style="border: 0; top: 0; left: 0; width: 100%; height: 100%; position: absolute;" allowfullscreen scrolling="no" allow="encrypted-media"></iframe></div>
</div>

## Highlights

### Make it easy to get started

This sounds like a no-brainer, but the best way to get people to try out your API is to make it really easy to get started.

We do things like including passable code snippets throughout our site and documentation. For example, one of the first things you'll see on our [front page] is a curl snippet you can paste into a terminal to simulate charging a credit card. Regardless of whether you have a Stripe account or not (if logged in, we embed your test API key, else, it's a sample account's API key), you can see the Stripe API in action.

All of our [documentation] code snippets are similarly easy to copy and paste&mdash;we try to embed as much information as possible (API keys, actual object IDs from your account) so you don't have to.

[front page]: https://stripe.com
[documentation]: https://stripe.com/docs/api

### Language-specific libraries and documentation

Since Stripe is an HTTP API, you could easily integrate it into your application with any HTTP client library. However, this still requires constructing requests and parsing responses on your own.

To make this easier, we support official open-source libraries in the [most] [popular] [web] [languages] today (turns out people are pretty attached to their favorite languages). There was a lot of internal discussion about whether we actually wanted to support our own API or allow the community to organically start and maintain the projects themselves.

Ultimately, I think there's a certain degree of trust that users put in official libraries, which makes it easy for them to get started (as opposed to trying to audit different third-party libraries). It also makes it really easy for us to have language-specific documentation this way.

[most]: https://github.com/stripe/stripe-ruby
[popular]: https://github.com/stripe/stripe-python
[web]: https://github.com/stripe/stripe-php
[languages]: https://github.com/stripe/stripe-java

### Have a focused API, but allow flexibility

One thing that we found critically important was to keep the API focused. It's tempting to add new features that are nice, but not necessary.

For example, our users frequently want us to add better analytics, tax calculations, or to send user receipts. While these things are nice, they're not our core competency and may very well clutter our API with too many options^1.

Instead, you should give your users the tools to be able to write their own extensions. We allow our users (and third party applications) to hook into Stripe in a couple of ways.

#### Webhooks

[Webhooks] are a way of Stripe letting you (our user) know when some interesting event has happened on the Stripe server. Examples include `charge.succeeded`, `charge.refunded`, `invoice.paid`, and so on.

With webhooks, it's easy to build something on top of Stripe events, like sending a customer receipts. This has the added benefit of allowing our users to control the entire user experience.

[Webhooks]: https://stripe.com/docs/webhooks

#### Stripe Connect

[Stripe Connect], an API we released just last year, is another way of building on top of the Stripe platform. Connect is an [OAuth2] API that allows a Stripe user to authorize access to their Stripe account to a third-party application. This application might be a marketplace, whose users want to accept payments, or an analytics dashboard, who wants to be able to have full access to Stripe data.

[Stripe Connect]: https://stripe.com/connect
[OAuth2]:

### Provide a testing environment

One of the most important things you need with an API is a test environment. This is particularly important for a payments API&mdash; obviously your users won't want to make live charges when they're trying to test their application.

In our testing environment, we allow you to send test web hooks of any type and provide handy test card numbers that trigger certain errors (like declines). Doing this allows our users to easily test the behavior of their own application in the face of different scenarios instead of having to manually trigger things that are nondeterministic, like declines, or time-dependent, like expiring subscriptions.

If there's certain behavior that your user's application potentially depends on, make sure they can test it easily.

### Help your users debug

We're developers too. We know that a large percentage of our users' time is probably spent debugging. We also (unfortunately) know that sometimes you spend a lot of time debugging something that eventually turns out to be really obvious or stupid.

For common or easy errors, you (the API) likely know exactly what's wrong. So why not try to help?

```
>> Stripe::Customer.create
Stripe::AuthenticationError: No API key provided.  (HINT: set your API key
using "Stripe.api_key = <API-KEY>".  You can generate API keys from the 
Stripe web interface.  See https://stripe.com/api for details, or email
support@stripe.com if you have any questions.)
```

Or,:

```
>> Stripe.api_key = TEST_KEY
=> ...
>> Stripe::Charge.retrieve("ch_17SOe5QQ2exd2S")
Stripe::InvalidRequestError: (Status 404) No such charge: ch_17SOe5QQ2exd2S;
a similar object exists in live mode, but a test mode key was used to make
this request.
```

If you help your users debug, they'll love you. 

### Dealing with Change

Lastly, dealing with change is never fun. As much as you hope you'll never have to change the API, sometimes you need to make changes, and sometimes those changes are backwards-incompatible.

There's no easy answer to versioning APIs. We keep a version per-user, which reflects the state of the API the first time they made an API request. This version isn't taken into account when we add a new feature or non-breaking change (i.e. you'll always be able to use new features, regardless of what version you're on).

Whenever we make a backwards-incompatible change^2, however, we bump the current version of the API (so that any new users will see the "new" changes) and take the legacy user's version into account in the relevant API code paths.

Users can choose to upgrade their versions in the dashboard (after reviewing the details changelogs, of course), or can send a version override header in any API request to test the behavior of a specific version.

## Questions?

If you have any questions, feel free to [email](mailto: amber@stripe.com) or [tweet](https://twitter.com/amfeng) at me. Thanks for reading!

**Footnotes**

1. I'm not saying that Stripe is not going to do these particular things in the future, but it's not feasible in general to try to accommodate everyone's use case.
2. We are usually hesitant to do this.

_Credit for various parts of the presentation content go to Greg Brockman, Sidd Chandrasekaran, Evan Broder, and Ross Boucher. And of course, credit to everyone at Stripe for actually doing the things I outlined in the talk._


Building Stripe's API


Consider the following code:

(This blew my mind the other day.)

```rb
class Hello
  def public_hello
    self.private_hello
  end

  private
  def private_hello
    puts "Hello!"
  end
end
```

You would expect that this would work fine: `private_hello` is a private method, but it's being called from within the class.

Nope.

```
>> hello = Hello.new
=> #<Hello:0x10d0cc200>
>> hello.public_hello
NoMethodError: private method `private_hello' called for #<Hello:0x10d0cc200>
  from (irb):3:in `public_hello'
  from (irb):13
```

I spent an embarassingly long time trying to figure out what was wrong (_"Do I just not understand how private methods work?!"_), and [confused one of my coworkers as well][1] in the process of doing so.

However, it turned out to be [old][1] [news][2]. [One post][3] puts the issue pretty succinctly:

> private methods can never be called with an explicit receiver, even if the receiver is self

So, the problem with `self.private_hello` is that the private method is being called on an explicit receiver, even though the receiver is technically the same object&mdash;you'd need to call `private_hello` by itself instead.

Having learned access control modifiers in Java first, I thought this was really bizarre. I guess I need to learn Ruby a little better! (:

[1]: http://twitter.com/maccman/status/281887326639108096
[2]: http://weblog.jamisbuck.org/2007/2/23/method-visibility-in-ruby
[3]: http://www.skorks.com/2010/04/ruby-access-control-are-private-and-protected-methods-only-a-guideline/
[4]: http://blog.zerosum.org/2007/11/22/ruby-method-visibility


Private methods in Ruby


I love career fairs. In college, I loved going to career fairs to get swag&mdash;EECS majors are definitely ridiculously spoiled when it comes to getting free things like shirts and food (I even got a poker set once!).

Anyway, while planning our trip to the [UC Berkeley Startup Fair](http://ucbstartupfair.com) this year, I wanted Stripe to stand out so I thought pretty hard about what my favorite types of things to get were.

Number one was shirts, probably. We already had that covered. But I also remembered happily going to the [Dropbox](https://www.dropbox.com) booth every semester to get those nifty free space cards: discount codes that you can apply to your account to get 5-10gbs of space at a time.

What if we made **free Stripe processing cards**? Since we'd be going to a career fair where all of the students were software engineers, and more specifically, very hacker/startup-minded, it made even more sense as a marketing effort.

<img src='/images/posts/discount-code-cards/discount-cards-blurred.png' style='margin: 30px 0'>

## Implementation

Most of the discount code implementation was already in place from our invite system, so all I really needed to do was generate an extra couple of hundred codes for use at the career fair. The hard part, however, was trying to figure out how to print them.

Traditional business card printing services won't let you print out cards with unique codes on them unless you go through some kind of custom order. I didn't have too much time to spare, so [John](http://johncollison.ie/) told me about this nifty hack he used with [Moo.com](https://moo.com) (I later found the same solution on [Quora](http://www.quora.com/How-can-I-print-business-cards-with-unique-codes-on-them/answer/Paul-Lewis-1/quote/96824)).

Moo lets you do this cool thing where you can print a variable number of designs per order&mdash;for example, if you want to have a different photograph on the back of each business card. We found that if you upload 100 different "designs" for 100 different cards, each card would be unique.

Their [Text-o-matic](https://secure.moo.com/start.php?productTypeName=minicard&contentSourceName=textomatic) tool lets you create up to 100 "designs" that are text only:

<img src='/images/posts/discount-code-cards/moo-text-small.png' style='margin: 30px 0; border: 1px solid #eee;'>

I took one look at the page and realized I could easily use a script to automatically generate all of the cards (sigh of relief when I discovered the page was not written in Flash):

```js
// Create an array of the discount codes you want to use here
var texts = ['CODE1', 'CODE2', 'CODE3'];

// Click buttons on the page for each code to create the design
texts.each(function(text) {
  jQuery('#txtFrontText').val(text);
  jQuery('div#divMakeCard input').click();

  // Set color/size
  jQuery('#a_000000').click();
  jQuery('#aReverseColours').click();
  jQuery('#aZoomOut').click();
  jQuery('#aZoomOut').click();

  jQuery('#btnSaveCard').click();
});
```

Really, really simple but pretty hacky (just run this in the developer console on the web page). After this, you'll just go into their general template wizard and upload the design for the other side of the card to finish them up.

## Improvements

Of course, there are several drawbacks to this approach:

* You can't really design the "variable" side of the card. You either need to upload the images yourself, or use Text-o-matic, which has a super limited set of options (you can't even add a new line or style separate parts of the text).
* You can only print 100 cards per order. Since the max number of designs you can upload is 100, if you try to double the card count to 200, you'll end up with every unique card twice.

So what can you do?

Probably the only legitimate way to do this is to generate the to-print PDF yourself, either using some kind of software (like InDesign) or hacking something in PostScript. I'll be sure to write a follow up post if I end up doing either!




Discount Code Cards


I love Git.

So much, in fact, that when I switched web hosts last month I decided to move all of my SVN repositories and put them on [Github](https://github.com/afeng) or into private Git repositories. Github's SVN import utility is painfully slow (and maybe even broken, I'm not sure) - so here's how to do it yourself. First, create a mapping from all SVN authors to Git authors in a file of the format:

    amber.feng = Amber Feng <me@amberonrails.com>
    (no author) = No Author <nothing@amberonrails.com>

Create a directory for your new Git repository and use the following git svn command to export:

    git svn --authors-file=path/to/authors_file clone SVN_REPO_URL LOCAL_DIR

You should now see log message `Initializing empty Git repository ...` followed by add, modify, and delete Git messages showing you the current status of the export.

The whole process can take from seconds to hours depending on how large the SVN repository is. Once, you're finished with the export, you can push the changes a hosted Git repository of your choice (Github, private, etc).



Exporting SVN to Git


Before you think about launching a site, make sure you have your bases covered! Here are the top three things I always have on my "checklist".

## Cross-browser Compatibility

This seems like a no-brainer, but I'm usually pretty bad with this because I like to test and debug all of my designs and applications in Chrome and ignore Firefox and (cringe) Internet Explorer (well, with the exception of IE9). I was brought back to my senses after I foolishly released the new version of my portfolio with a gaping Javascript bug that broke in all versions of Firefox. Ever since, I've been testing my websites in all browsers - even going to great lengths to install Internet Explorer on my Macbook Pro.

There are a couple of websites I'd recommend for doing this:

- [BrowserShots](http://browsershots.org) is a website that takes a URL (mind that this doesn't work with localhost) and a list of browsers, returning a collection of screenshots taken of your site rendered in each of the different browsers. I've found this website pretty useful with making sure that my CSS styling and images are showing up correctly, but of course you can't actually play around with the website or test the Javascript. Did I mention it's free?

- [Adobe BrowserLab](https://browserlab.adobe.com) is another super cool screenshot service with a really nice interface (what do you expect, it's Adobe) and handy features like viewing screenshots from what they call "browser sets" side by side and overlaying screenshots on top of each other. There are lots more features that I'm too lazy to put in this post, but you can view them [here](https://browserlab.adobe.com/en-us/features.html)! I don't think it's free, but I was able to sign up for a complimentary one year subscription.

- If you'd like to actually like to test out your application, you might consider using [CrossBrowserTesting](http://crossbrowsertesting.com/) (aptly named), which allows you to remote into their testing machines and actually try out your application in a bunch of different browsers and operating systems. I've never actually tried them before, but I've heard good things about the service. It's a little pricey, around $20 a month for 150 minutes of testing time a month. 

  **Pro Tip**: don't accidentally leave your session with them open on your browser.

## Analytics

If you're like me, aka you take great pleasure in looking in all the page view statistics on all of your websites, you'll love having analytics installed. Make sure you install analytics BEFORE your launch, or you'll be sorry you missed out on the exciting graphs (I deeply regretted forgetting to install analytics on REOrganize before I launched).

I highly, highly recommend [Google Analytics](http://analytics.google.com) (free, as with almost every Google product). It's really easy to set up - you just insert a Javascript snippet on the page(s) you want to be tracked, and let Google do the rest of work! There are too many cool features to name, and I won't pretend to be an analytics expert. If you're really into analytics, you should check out Avinash Kaushik, a guru over at Google who has pretty interesting analytics insights over at his [blog](http://www.kaushik.net/avinash/).

## Exception Notification

If you're launching a web application (vs. a static page), it's essential that you have exception notification. Standard exception notification services will email you if any exception is raised in your application along with a log/stack trace, and may even offer premium features. You can usually find plugins for whatever app framework you're using - for example, Rails has an [exception notification plugin](https://github.com/rails/exception_notification) you can install that
uses your server's mailer.

(**Update**: I've written a post on how to use exception_notification [here](http://www.amberonrails.com/2011/02/rails-exception_notification-setup/))

If you don't want to worry about installing anything, you can go for one of the many web services out there. I've used [HopToad](http://hoptoadapp.com/pages/home) before, which offers a free "Egg"
plan for one application and comes packaged with a gem you can easily install in a Rails application. [Exceptional](http://www.getexceptional.com/) is quite good as well, but only for Rails (I basically only know about Rails services, if you haven't noticed already).


## Conclusion

These are the top things that I'd recommend that most people never think to do before launching a website; maybe I'll mention some smaller (but still important!) things to check for in a future post.

PS: Merry Christmas/Happy Holidays!



My Launch Checklist


On the first day of my Algorithms class here at school, we learned three ways to implement the well known [Fibonacci series](http://en.wikipedia.org/wiki/Fibonacci_number) generating algorithm.

## Standard recursive

Everyone and their mom knows the recursive way to implement Fibonacci:

```rb
def fib(n)
  return 1 if n < 2
  fib(n-1) + fib(n-2)
end
```

This is an extremely inefficient algorithm - the running time is exponential, growing almost as fast as the Fibonacci numbers themselves! For example, to find the 200th Fibonacci number, the algorithm takes 2^138 steps! Obviously this is not feasible to compute even on a modern computer.

What's the problem with this algorithm? We can see that we are repeatedly computing the value of each Fibonacci number (ex. for the 4th fibonacci number, we need to add the 3rd and 2nd, and to calculate the 3rd, we need to add the 2nd and 1st, and etc).

## Memoization

One way we can avoid this double-counting is to remember what Fibonacci values were already computed in a hash table so we don't have to launch into another recursive call for a value we already have. We can also switch to implementing this with an iterative method:

```rb
def fib(n)
  fibHash = [1, 1]
  for i in 2..n
    fibHash.append(fibHash[i-1]+fibHash[i-2]
  return fibHash[n]
end
```

Now this is pretty clever, but who knew that there was an even MORE clever mathematical way to tackle this problem?

Consider the following equations that represent the Fibonacci series:

![](/images/posts/fibonacci-times-three/1.png)

We can write the first two equations in matrix notation:

![](/images/posts/fibonacci-times-three/2.png)

The rest of the equations may be written in matrix notation, and if we substitute the value for [F1 F2] from the first equation, we notice a pattern:

![](/images/posts/fibonacci-times-three/3.png)

![](/images/posts/fibonacci-times-three/4.png)

Now wait a minute - have we really figured out a way to make an O(1) algorithm for the Fibonacci series?

Unfortunately, we need to take the multiplication and power operation runtimes into account because they are computationally more expensive than doing addition on large numbers. With the performance cost of using multiplication, we see that that runtime of this matrix implementation is actually O(n^2), which is sadly not faster than our O(n) algorithm.

**Credit**: Material and screenshots taken from [Algorithms by S. Dasgupta, C.H. Papadimitriou, and U.V. Vazirani](http://www.cs.berkeley.edu/~vazirani/algorithms.html).



Fibonacci Times Three


Lately I've been really into doing Google Codejam practice problems (aka I'm a nerd). I discovered I really need to brush up on my algorithms ):

## The Problem

The decimal numeral system is composed of ten digits, which we represent as "0123456789" (the digits in a system are written from lowest to highest). Imagine you have discovered an alien numeral system composed of some number of digits, which may or may not be the same as those used in decimal.

For example, if the alien numeral system were represented as `oF8`, then the numbers one through ten would be `F, 8, Fo, FF, F8, 8o, 8F, 88, Foo, FoF`. We would like to be able to work with numbers in arbitrary alien systems.

More generally, we want to be able to convert an arbitrary number that's written in one alien system into a second alien system. [Complete problem here](http://code.google.com/codejam/contest/dashboard?c=32003#).

## My Solution (Ruby)

```rb
def hash_indexes(arr)
  hash = {}
  
  for i in 1..(arr.length - 1)
    hash[arr[i]] = i
  end
  return hash
end

def log(base, num)
  Math::log10(num)/Math::log10(base)
end

def to_decimal(source, num)
  num_arr = num.split("")
  hashed_source = hash_indexes(source.split(""))
  dec = 0

  for i in 0..(num_arr.size - 1)
    hashed_no = hashed_source[num_arr[i]].to_i
    dec += hashed_no * (source.size ** (num_arr.size - 1 - i))
  end
  return dec
end

def to_target(target, decimal)
  final = ""
  target_arr = target.split("")
  
  i = log(target.size, decimal).to_i
  while i >= 0
    value = target.length ** i
    times = (decimal/value).to_i
    final << target_arr[times]
    decimal %= value
    i -= 1
  end
  return final
end

def solve(line)
  arr = line.split(" ")
  to_target(arr[2], to_decimal(arr[1], arr[0]))
end

file = File.new("A-large-practice.in", "r")
output = File.open("A-large-practice.out", "w") do |f|
    num_lines = file.gets.to_i
    for counter in 1..num_lines
      solution = solve(file.gets)
      f.write("Case ##{counter}: #{solution}n")
      #puts "Case ##{counter}: #{solution}"
    end
end
file.close
```
    

**Time to solve:**

- `A-small-practice.in` - 5.7ms

- `A-large-practice.in` - 15.1ms


Google Code Jam: Alien Numbers


I've been trying to learn more about using command line SVN because I'm not terribly familiar with it, here is a super quick reference guide to the most common/useful SVN commands.

###Checking out a repository (with optional username/password flags):

    svn checkout [SVN REPO] [LOCAL DIR] --username [USER] --password [PASS]

###Copying a clean directory tree (no svn config files or folders):

    svn export [PATH FROM] [PATH TO]

###Updating/Committing local copy:

    svn update
    svn commit -m "[MESSAGE]"

Recently, I've also had to figure out how to ignore folders and files that I don't want committed to my repository (ex. local performance profiling data). I found the following useful commands in the [SVN Book](http://svnbook.red-bean.com/en/1.0/):

###Ignoring files/folders

    svn propset svn:ignore bin .
    svn propset svn:ignore hello.gif .

###Un-ignoring files/folders

    svn propdel svn:ignore bin .
    svn propdel svn:ignore hello.gif .

###Viewing ignored files/folders (and/or editing in an editor of your choice)

    svn propget svn:ignore .
    svn propedit svn:ignore . --editor-cmd vim



SVN Ignoring Files/Directories


I've recently had inspiration for a new web application that fits my needs as a web designer (it's a secret for now), but it's not a standard CRUD web app so it requires a fair amount of new programming/customization that I'm struggling with.

One thing the application requires that I'm not sure how to do is automatically capturing website screenshots. I'd like some sort of service where I feed in a URL and it spits out an screenshot of the website at that URL. Researching on Google, I've found many commercial types of software that can accomplish this but I'd like to use some type of open source plugin or web service.

Furthermore, I'm planning on using this for my own web application so I'm not sure what the legal implications are. I'd like to write my own software for this, but I'm not quite sure how to start or what this would entail.

So far, I've found some interesting links that are almost exactly what I'm looking for.

  * Binary Moon found a that Wordpress had their own service for doing [automated screenshots](http://www.binarymoon.co.uk/2010/02/automated-take-screenshots-website-free/) (ex. for theme galleries) with dynamic URLs, but I'm not sure Wordpress would be too happy if I spammed their servers with something non-Wordpress related.
  * I've also found this website called [Miwim](http://translate.google.com/translate?js=y&prev=_t&hl=en&ie=UTF-8&layout=1&eotf=1&u=http://thumbs.miwim.fr/install.php&sl=auto&tl=en) (it's in French, but I've applied a Google Translate) that offers a similar service. The only downside is you have to link back to the service -- which I'm sure I'd do, anyway.
  * Paul Hammond has also written a command line tool called [webkit2png](http://www.paulhammond.org/webkit2png/) that accomplishes the same thing, but I'm not sure how to run terminal commands from a web application.
  * Here's another [forum](http://www.fluther.com/17263/take-web-screenshots-for-a-website/) that offers some alternatives, though some of the links are long dead.
I'm still searching for other services/ways to do it myself..if you have any
ideas I'd love to hear them!



Automatically Capturing Website Screenshots


Recently, I re-stumbled upon a website that I absolutely love using for choosing or playing around with different color schemes, [Color Scheme Designer](http://colorschemedesigner.com/). Visually stunning, this online tool includes a color wheel where users can intuitively drag around color selectors and a number of scheme types such as "Mono", "Complement", "Tetrad" that automatically show schemes for real-time color selections.

![](/images/posts/color-scheme-designer/1.png)

Color Scheme Designer also provides random presets (in case you're lacking inspiration), advanced color customization, and handy hover-over hex codes for any desired colors.

There is even a "vision simulation" to show you how the colors would look from the view of someone with visual impairments! And "scheme previews" to show you how your color scheme would look on a basic table-based layout! Amazing -- definitely a find worth sharing.

![](/images/posts/color-scheme-designer/2.png)


←

misc