Day 5: Exploring Inspire’s Server-Side API w/Zach

It’s best to keep the API representation of an object separate from the object itself so even though Rails provides #as_json and #to_json methods. It can be tempting to use them, to evolve them, and to build around them, but in my experience it’s best avoid them.

APIs dont’t usually consist of all of the data that are housed in your system, so you need to selectively choose what to support on a public API. And then you need to be able to support versioning the API, permissions of what data can be seen, etc. I recently heard about Grape so I decided to give it a look.

Grape is a micro-framework for creating REST-like APIs, but it primarily appears to help with organizing API route/endpoint definitions. After a short spike it wasn’t solving my primary concern: cleaning how the API content is generated simple, clean, and as close to the end-point as possible. So I decided to explore rabl.

Rabl is a Ruby API templating language. This means that rather than using erb or haml to write your APIs, you write rabl templates. At first the syntax seemed a little strange, so I decided to spike on representing an endpoint which involved multiple objects and required nesting. Here’s two example rabl files from the spike.

First, the index template:

# index.json.rabl
object false
code(:people) do |m|
  @contacts.people.map do |c|
    partial("api/v1/contacts/_person", \:object => c)
  end
end

And the partial used for representing a person:

# _person.json.rabl
object @person
attributes :id, :first_name, :last_name, :title, :dob, :gender, :about

code(:websites) do
  if locals[:object].present?
    locals[:object].websites.map do |w|
      { 'type' => w.value_type, 'url' => w.value }
    end
  end
end

code(:phone_numbers) do
  if locals[:object].present?
    locals[:object].phone_numbers.map do |w|
      { 'type' => w.value_type, 'url' => w.value }
    end
  end
end

code(:email_addresses) do
  if locals[:object].present?
    locals[:object].email_addresses.map do |w|
      { 'type' => w.value_type, 'url' => w.value, 'default' => w.default }
    end
  end
end

code(:addresses) do
  if locals[:object].present?
    locals[:object].addresses.map do |w|
      {
        'type' => w.value_type,
        'address' => w.full_address(:include_country => true),
        'default' => w.default
      }
    end
  end
end

code(:instant_message_accounts) do
  if locals[:object].present?
    locals[:object].instant_message_accounts.map do |w|
      { 'type' => w.value_type, 'url' => w.value }
    end
  end
end

code(:groups) do
  if locals[:object].present?
    locals[:object].groups.map do |w|
      { 'name' => w.name, 'id' => w.id }
    end
  end
end

While there are some improvements that can be made with rabl’s syntax it promotes a good separation between the model and the API. I really liked that. This will help keep API versioning and endpoints cleanly separated from how the underlying models evolve or implementations change.

Advertisements

Day 2: Mark + Victor, iOS Interface Meeting

While Chris and Sung were working on the Android, Mark and Victor were at the office working on the app design for iPhone iOS. Here’s some markerboard drawings from their session.

(Click to view bigger)


Day 2: Chris + Sung, Android Interface Meeting

Last night, Chris and Sung met at the Meanwhile to discuss the interface for their Android app.  There’s a little more pressure on them because the actual customer request for a mobile Inspire app came from an Android user.

Being that neither Sung nor Chris are Android users, they had to spend some time studying Android’s design patterns to determine a layout that would make the most sense to an Android user.  By the end of the night they had notecard comps of the contact list and log-in page with a few housekeeping features.

Soon the sun set and there were no lights nearby on the deck.  I found the setting on the camera that allows me to shoot in extremely low light even after I’ve cranked the ISO all the way up.  Unfortunately I didn’t find this setting until three seconds after Chris and Sung had finished explaining their night to me.  Basically what I’m saying is, enjoy the last minute of cinematography.  I’ve included plenty of freeze frames so you can see what they’re referring to.

[vimeo vimeo.com/28775441]

Some artifacts from their night:



DataTemplate and PhoneApplicationPage.Resources Gotcha

When building an interface for a windows phone 7 mobile app you may want to use what are called DataTemplates to build your UI in chunks. Something like a list of accounts, you might want to create a DataTemplate to represent the singular Account within in the UI and bind it to a single ‘Account’ Model. In most fo the examples I found online about this they all displayed the DataTemplate XAML but never in context. Well it turns out you can’t just add those anywhere.

DataTemplate is expected to live into a tag named PhoneApplicationPage.Resources. which lives inside your top level PhoneApplicationPage XAML tag.

So it should look like this:


Day 1 Video

 

Some fly-on-the-wall videos of the initial meeting, team planning, story mapping, and thoughts from the developers and designers.

[vimeo vimeo.com/28716737]

Day 1 Bonus Video

Some fly-on-the-wall videos of the initial meeting, team planning, story mapping, and thoughts from the developers and designers.

[vimeo vimeo.com/28714387]

Storymapping Con’t.

Click to view bigger.