Using API-First Design at Hackathons

How to Hack Your Way to Productivity

The challenge of any hackathon is the lack of resources and the time constraint. It boils down to this, you don’t have enough time and you don’t have enough people to accomplish exactly what you set out to do. The lack of resources should drive your decisions in every aspect of your hack. For example, Heroku is a great deployment choice because getting an app running is as simple as:

 git push heroku master

Stripe is an awesome payments platform because charging a credit card is as easy as:

curl https://api.stripe.com/v1/charges \
 -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
 -d amount=400 \
 -d currency=usd \
 -d card[number]=4242424242424242 \
 -d card[exp_month]=03 \
 -d card[exp_year]=2020 \
 -d “description=Charge for test@example.com”

Lob is an awesome service for fulfilling physical products because sending a postcard to someone is as easy as:

curl https://api.lob.com/v1/postcards \
 -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
 -d “name=Test Lob Postcard” \
 -d “to[name]=MIT” \
 -d “to[address_line1]=77 Massachusetts Ave” \
 -d “to[address_city]=Cambridge” \
 -d “to[address_state]=MA” \
 -d “to[address_zip]=02139" \
 -d “to[address_country]=US” \
 -d “front=https://www.lob.com/postcardfront.pdf" \
 -d “back=https://www.lob.com/postcardback.pdf" 

The point is that you have limited resources and your time is best spent on your hack rather than trying to reinvent a service someone has already created. In the same way you shouldn’t reinvent services, you shouldn’t reinvent the software design process. We believe that API-first design is the most efficient way to design an application at a hackathon.

API-first design is the most efficient way to design an application at a hackathon because it allows teams to allocate their limited resources between the front and back-end in the most efficient way. The initial step of API-first design is to determine the contract that will determine how the front end and back-end will interact with each other. This can take the form of a whiteboard session or team members talking over a Google Document or notebook. This is a very valuable step and can be a great creative platform for technical and non-technical team members alike. This discussion should be focused on both the objects and actions that your application will address. In the ubiquitous “micro blog” example this would look something like:

• Our application will have many users
• Each user will have many posts

Taking these basic design decisions a step further would result in the following API implementation:

Objects:

User Object: {
    id: <integer>,
    name: <string>,
    email: <string>,
    posts: [<Post>]
}
Post Object: {
    id: <integer>,
    title: <string>,
    body: <string>
}

Endpoints:

User Actions:

• GET /users — get a list of all users we have
• GET /users/<user_id> — get info for a single user
• POST /users — create a new user
• POST /users/<user_id> — update an existing user
• DELETE /users/<user_id> — delete an existing user

Post Actions:

• GET /users/<user_id>/posts — get a list of all posts by a user
• GET /users/<user_id>/posts/<post_id> — get an existing post
• POST /users/<user_id>/posts — create a new post for a user
• POST /users/<user_id>/posts/<post_id> — update an existing post
• DELETE /users/<user_id>/posts/<post_id> — delete an existing post

Of course this is a trivial example of design, but the idea is that you can translate the basic concepts of an application (the objects and actions) into JSON objects and RESTful endpoints without having to write a single line of code. The goal of this exercise is to create and understand the separation of concerns between the front-end and back-end of your application. Once you have done this, it makes it much easier to allocate your resources in a “divide and conquer” fashion.

Regardless of whether the front-end of your application is Angular, iOS, Android, or a static site built on Ruby, Python, PHP, etc. it will be able to consume your RESTful JSON API. Likewise, any server-side language or framework you choose can easily serve as a RESTful JSON API (e.g. Rails::API, Python and Flask, Sails.js in Node).

Once you have decided on both your front-end and back-end stack you can start development simultaneously. It is relatively simple to mockup a back-end server that adheres to the contract drawn up by the team at beginning. You can check out this repo for a very simple example of how the micro blog API can be mocked in Node.js.

Deploying even a bare-bones implementation of the back-end server should be enough to allow the front-end team to get up and running. While the front-end team is creating their interface using the mock API server the back-end team can focus on building out the rest of the functionality, (authentication, data persistence, external APIs, etc.). There’s no reason to stall the designers and front-end developers while you pick a data store!

Everyone participating in a hackathon has only a finite amount of people and time, therefore, how you utilize your time and resources is of the utmost importance. Creating your application using API-first design minimizes the amount of friction between the front-end and back-end of your application and allows your team to focus on delivering the best possible version of your application during the event.

Do you think there’s a better way to approach application design during a hackathon? Let us know by commenting or tweeting at me!