Interfacing with an API is a big part of web development and design these days. APIs help provide a rich, dynamic experience in the browser. Rather than static markup and images, you can dynamically push and pull data from a server and render it in the browser based on the experience you want to provide for the user.
In this tutorial, we’ll build a basic example of an API-based app. Using the iTunes API, we will take the URL of any iOS or Mac app and render its full resolution icon right in the browser. This specific app might not be immediately useful to you, but what you learn along the way can be applied to all manner of scenarios.
Overview
Most properly designed iOS and OSX apps provide high-resolution assets for their icon artwork. Sure, those icons may only appear to be 150×150 pixels in size on your iPhone springboard, or your OSX dock, but to account for retina screens and different sizing requirements across the operating system, Apple requests that app makers provide high-resolution icon assets, as large as 1024×1024 pixels! For example, on the left you’ll see the Tweetbot for Mac icon as it would approximately appear in your OSX dock. While on the right is the full resolution image:
Apple makes these assets accessible via the iTunes API. So if you ever want to get the high-resolution, full-sized artwork, you can! All you need is the app’s identifier, then by making a request to the API you will be given a bunch of info about the app, including a link to the highest resolution artwork the store has available.
This tutorial is not so much about learning the iTunes API as it is about learning some of the basic concepts behind building a dynamic web app that renders content returned from an API. Once you learn the basics of interfacing with an API, you can go on to build your own personalized web sites using third-party APIs, like Dribbble or Twitter.
As a quick overview, here are the concepts we’ll cover in this tutorial in order to achieve the end product:
- Wireframe the basic experience
- Produce mocks in Sketch
- Build in HTML/CSS
- Add interactivity via JavaScript
Wireframes
In order to understand what we are going to be building, let’s start by detailing the basic experience of our little app. Once that is complete, we can get a little more specific by listing its component parts.
The App’s Basic Experience
In order to start wireframing the app’s component parts, we need a list of the app’s basic functionality and experience:
- Request an iOS or Mac app store link (such as https://itunes.apple.com/us/app/twitter/id333903271?mt=8) from the user
- Verify the link is valid and make a request to the iTunes API based on it
- Parse the API response, making sure it’s valid and collecting the relevant info
- Display either an error or the full-size icon artwork returned from the API
The App’s Component Parts
Now that we have a basic understanding of what we want the app to accomplish, we can start wireframing its different parts. Keep in mind that we’ll want this to be a responsive web app, so we will make sure to design our parts in a way that allows them to size up and down responsively.
Header: At the top of the page, we’ll have some stylized text that represents the name of the app, along with a short description of what it does. “Gimmie Dat iCon” is the silly name I’ve come up with for our app.
Input: We need to provide a way for the user to input a link to the app whose icon artwork they want. For this we’ll add a simple input field and submit button right under the header.
Output: Once a valid link is retrieved from the user, we’ll need a space to display the icon artwork retrieved from iTunes. So we’ll create a spot for that right under the input field.
That’s about it. We now have all the basic component parts we’ll need in order to retrieve a link from the user and display information coming back from the iTunes API.
Component Part States
There’s one other important factor we need to consider in our wireframe stage: the different states of our component parts. Our little app is going to be in different states at different times. For example, we know we need to show the icon artwork returned by the iTunes API, we’ve already accounted for that. But what if the API returns an error, then what do we do? Or what if the user enters a bad link? We need to account for the different states our app may be in, depending on its state of execution. As our app is pretty simple, we only have these few use cases we need to cover:
Zero state: What happens when the user first comes to our web page? There’s no icon artwork to display because they haven’t entered a URL yet. So we’ll need some type of friendly “zero state” that says “hey, you haven’t entered a link yet. Go ahead and enter one then we’ll display the icon here.”
Errors: It’s very possible that a few errors may occur during the execution of our app. For example, the user may enter an invalid URL. Or, the iTunes API may return bad data, or no data at all. We should account for these cases in our app’s design so the user isn’t left wondering what went wrong. So we’ll design a way to show an error message (whose text will change, depending on the error).
Loading: Because we’re working with an API, not everything will happen instantaneously. The user’s computer has to make a request to a third-party server, which has to compute the request and send back the information. This could take up to a few seconds to occur. So we will make sure our app’s design provides a way of communicating that the content is loading. That way the user doesn’t get frustrated and confused by a static screen where nothing is happening (even though content is loading in the background).
That’s it! We’ve covered all our different component parts and their various states. In the next tutorial we’ll move on to visually designing the app with more detailed wireframes.
