Why Building a Mobile App is Hard

Kent Nguyen has a great article about how building iOS apps takes a lot of work. And, here at Parse, we agree. Making a well-designed app is not a trivial task. Many non-developers hugely underestimate the amount of sweat and tears that goes into a single app.

The big component that is overlooked and that Kent stresses is the server component. An app is not an island. Users expect their apps to richly interact with the internet.

This means you need to worry about developing code on servers, communicating with servers, APIs, and a whole plethora of network issues.

And this is the exact reason why we built Parse. We have your back when it comes to server-side components.

But let’s ask the question: why is building a mobile app with a server component so hard? To answer that, we need to take a step back.

Replatforming is Hard

We are currently going through a huge replatforming. It just so happens that the big endpoints for the internet aren’t desktop computers, but rather, mobile devices. This has huge ramifications.

Let’s go back to the 90s. Desktop software ruled the roost. Most apps didn’t talk to the internet, and, even if they did, it would be a simple phone home operation. App developers could dutifully create an app, test it on their desktops, then deliver it as a download to end users.

As the 00s emerged, apps started shifting onto the web. Suddenly, developers were programming servers to render static content that would be served to browsers. Most of the heavy duty lifting was being done server-side.

Now, let’s fast forward to the present. It’s clear that mobile will be the dominant platform for the foreseeable future. But, building a mobile app comes with the challenges of both desktop software and web apps. You need complicated client-side logic to provide a great user experience, but, you also need servers to persist data and provide a connected experience for users.

We have entered an age of a hybrid architecture. We now have to deal with fat clients and fat servers.

All of this means that developers have to be client-side and back-end wizards in order to deliver a successful app. On top of all this, the mobile world is still relatively young, and a lot of the tools we’ve built for the web have not transitioned over to mobile.

Platforms Will Save the Day

We believe that the server component of apps isn’t where mobile developers should be spending their time. They should focus on their app’s user experience. Platforms will be instrumental for developers to build rich apps and reduce their time to market.

It’s an exciting time for developers right now. We have the ability to reach more people on earth with our code than ever before. And, it’s only just the beginning.

James Yu
January 31, 2012

Networking Improvements in PFFile and ParseFile

Last week we announced file support in the REST API. Hot on the heels of that announcement, we’ve made many improvements to PFFile and ParseFile:

  1. Both classes are now resilient to a wide assortment of network conditions. Parse will automatically retry uploads of new files and fetches of existing files.
  2. Uploads and downloads can be cancelled at any time using the new cancel methods on both classes.
  3. Both classes can take callbacks to report progress. For example, to
    monitor the progress of an upload in iOS:
NSData *data = [@"Working at Parse is great!" dataUsingEncoding:NSASCIIStringEncoding];
PFFile *file = [PFFile fileWithName:@"resume.txt" data:data];
[file saveInBackgroundWithBlock:^(BOOL succeeded, NSError *error) {
  // Handle success or failure here ...
} progressBlock:^(int percentDone) {
  // Update your progress spinner here. percentDone will be between 0 and 100.
}];

Read more about the progress callbacks in the iOS Guide and Android
Guide
.

As always, let us know what you think.

Ilya Sukhar
January 30, 2012

Uploading Files via REST API

No matter if you are building a video, music or reading app, it is likely you’ll run into the following dilemma. Initially you package all your contents into your app, only to discover that the app is about 2GB in size, and contains only static content. No user will want a bloated app like that, you say.

How do you solve this problem? One simple solution is to upload your files to your Parse backend, so that your mobile app is small in size. As the files are needed, the app can download the dynamic content on the fly from the backend.

Indeed, for mobile apps, a common usage of the backend is to serve files. But how do you upload the files to the Parse backend?

Today we’ve added a simple but very useful feature: file uploading using the REST API. Suppose you want to upload a file named “hello.txt” to your Parse backend, you can run the following command:

curl -X POST 
  -H "X-Parse-Application-Id: ${APPLICATION_ID}" 
  -H "X-Parse-REST-API-Key: ${REST_API_KEY}"     
  -H "Content-Type: text/plain" 
  -T 'hello.txt' 

https://api.parse.com/1/files/hello.txt

As simple as that, the file is uploaded to your Parse backend! You can read the response to find out where the file is:

{ "url": "https://...hello.txt", "name": "...hello.txt" }

Read more in our REST API documentation.

Let us know how else Parse can make your lives easier; we would love to hear from you!

Andrew Wang
January 25, 2012

Javascript and User Authentication for the REST API

At Parse, our vision is that anything you can build with your own backend server, you should be able to do with Parse instead. We’ve been constantly impressed by the things developers have been building with the Parse REST API. In particular, a lot of developers use Parse not just to build mobile apps, but also to build mobile websites. To make this easier, we’re launching several improvements to the REST API today.

First, we’re launching support for cross-origin resource sharing, so that you can use Parse from Javascript that runs on any site. With the X-Parse-Application-Id and X-Parse-REST-API-Key headers, so that you can access Parse from Javascript on any domain. This works for all CORS-compatible browsers, which includes all Android and iOS browsers. Here’s some sample code to create a Message object with an XMLHttpRequest:

var xhr = new XMLHttpRequest();
xhr.open("POST", "https://api.parse.com/1/classes/Message", true);
xhr.setRequestHeader("X-Parse-Application-Id", "your application id");
xhr.setRequestHeader("X-Parse-REST-API-Key", "your REST API key");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.onreadystatechange = function() {
  if (xhr.readyState == 4) {
    var result = JSON.parse(xhr.responseText);
    if (result.objectId) {
      alert("saved an object with id: " + result.objectId);
    }
  }
}
  
var data = JSON.stringify({ message: "Hello world!" });
xhr.send(data);

The REST API also now supports the same user-based security that the iOS and Android SDKs support, so that you can control access to user data. The user gets authenticated by passing the X-Parse-Session-Token header. This works using CORS from Javascript, as well as anywhere else you access the REST API. Read more about it in the REST API Users documentation. Parse is always backward-compatible, so code that uses older methods of authentication will still work.

We built these features because we heard from so many developers telling us that they would be useful. So please, keep in touch, let us know what you’re building and how we can make your life easier.

Thanks for using Parse!

Kevin Lacker
January 19, 2012

Migrating SimpleGeo Customers: Idea to Production in One Day

Last Thursday started out like any other. We got into the office, had our daily stand up meeting, did some work, ate some tasty catered food, and were humming along in our usual routine. Somewhere in the afternoon things took a different turn. Here’s the play by play of how we launched a one-click migration tool for SimpleGeo Storage customers in one day.

2:03 pm

I finish up whatever I’m doing and load up Hacker News for a quick break. I notice a story about Urban Airship shutting down SimpleGeo and paste the link into our HipChat room. We discuss the Hacker News commentary. It seems people are upset with the shutdown.

2:05 pm

Kevin asks “can we reach out to people who were using simplegeo storage somehow?” James immediately counters with “we should make a migrate your account landing page!”

2:12 pm

We take a look at SimpleGeo’s documentation and map each of their constructs (Layers, Records, Locations) to ours (Classes, Objects, GeoPoints). It seems reasonable.

2:12 pm – 2:25 pm

Rapid discussion ensues. How long would it take? Is it worth it? How good are the suggested migration options? Do we write a script that people can download or provide a service? Do we have an account to use? Are their APIs robust enough to allow a wholesale export?

2:25 pm

It’s on:

2:25 pm – 2:46 pm

James starts working on the landing page. I start on the backend by looking at the SimpleGeo API for the first time. I fire up curl and try to make some sample data. I hit a snag immediately. I don’t have “write access to the layer.” Huh? How do I create a layer? I panic a bit. I don’t see it in the docs. Maybe new layer creation is disabled? Things
look a little dire on my side.

After a little head bashing, it turns out that I’m too accustomed to our philosophy at Parse of “zero configuration to get up and running.” You have to create a new layer in the web UI.

2:55 pm

James comes up with the idea of having a visual hook — a neat icon to represent the core of what the importer is doing. He spies a lifesaver image and immediately knows what the design should look like.

3:05 pm

James has the landing page mocked up:

3:32 pm

I have a rough script up and running:

3:32 pm – 5:35 pm

We crank our headphones and hack.

5:35 pm – 7:03 pm

I merge in my code and we start testing it together end-to-end. We find various bugs around state transitions in the backend and frontend. We decide to have the backend periodically notify the frontend about how many objects it has processed. We test, fix bugs, iterate on the UI, repeat.

7:03 pm

I merge our branch into master, push to production, and spin up the import workers. We declare victory and show it to a select few people.

12:14 am

James discovers a bug and we discuss it in HipChat. We declare victory again.

Friday

We post the importer on Hacker News. Jason Kincaid at TechCrunch picks
up the story
. James creates a walkthrough video to illustrate the
import flow:

Just another day at Parse :-)

We’re currently hiring smart hackers to come and build the platform with us.

Ilya Sukhar
January 16, 2012

Designing Great API Docs

Writing documentation is one of those things that is dreaded by many developers. It takes a lot of effort and time to get right. And too often, people take shortcuts. This is sad, because well designed documentation is the key to getting people excited about your project, whether it’s open source or a developer focused product.

In fact, I argue that the most important piece of UX for a developer product isn’t the homepage or the sign up process or the SDK download. It’s the API documentation! Who cares if your product is the most powerful thing in the world if no one understands how to use it.

If you’re a making a developer focused product, the documentation is as core to the user experience as the endpoints themselves.

I’ve seen far too many projects that simply dump you to a GitHub page with a two-liner readme. The most successful API docs are carefully crafted with love. Here at Parse, we devote ourselves to this art.

So, what elements go into making great API documentation?

Documentation is a Layered Beast

Your documentation shouldn’t just be a plain listing of endpoints with their parameters. Documentation is a whole ecosystem of content that aims to teach users how to interact with your API. At the very least, you should have these components:

  • Reference: This is the listing of all the functionality in excruciating detail. This includes all datatype and function specs. Your advanced developers will leave this open in a tab all day long.
  • Guides: This is somewhere between the reference and tutorials. It should be like your reference with prose that explains how to use your API.
  • Tutorials: These teach your users specific things that they can do with your API, and are usually tightly focused on just a few pieces of functionality. Bonus points if you include working sample code.

At Parse, we have all three of these components, and we’re currently working on fleshing out more tutorials.

Another good example is Stripe’s API, which has an awesome hybrid guide and reference and also a cadre of great tutorials. GitHub’s reference API is also very well designed.

Remove Abstractions with Examples

You could argue that your API is one big abstraction, and that’s kind of the point. However, when teaching developers, try to remove as many abstractions as possible.

Liberally sprinkle real world examples throughout your documentation. No developer will ever complain that there are too many examples. They dramatically reduce the time for developers to understand your product. In fact, we even have example code right on our homepage.

Minimize Clicking

It’s no secret that developers hate to click. Don’t spread your documentation onto a million different pages. Keep related topics close to each other on the same page.

We’re big fans of long single page guides that let users see the big picture with the ability to easily zoom into the details with a persistent navigation bar. This has the great side effect that users can search all the content with an in-page browser search.

A great example of this is the Backbone.js documentation, which has everything at your fingertips.

Include a Gentle Quickstart

The hardest part of adopting a new API is right at the beginning, where the learning curve is steep and the developer is exposed to complicated new ideas. The solution to this is to introduce the API with a quickstart guide.

The goal of the quickstart is to walk the user through the minimal steps needed to do the smallest thing possible in your API. Nothing more. Once a user has done this, they’re ready to move on to the more advanced concepts.

For example, our quickstart guide has the user download our SDKs and then save one object to our platform. We even have a button that lets users test whether they’ve done this correctly. This gives them the confidence to move on and learn the rest of our platform.

Use Multiple Languages

We live in a polyglot world. If appropriate, try to list examples for multiple languages that your API supports, most likely via client libraries. Learning a new API is hard enough without having to parse unfamiliar languages.

MailGun’s API does a great job of this by letting developers choose between curl, Ruby, Python, Java, C#, and PHP for the examples in a global menu.

You Can Never Over-communicate Edge Cases

The worst thing is to be developing with an API only to discover an error state that isn’t documented. In situations like this, it can be unclear if the error is in your code, or in your understanding of the API.

Your reference should include every edge case and every assumption that is made, either implicitly or explicitly. Spending a few minutes doing this can save hours of your user’s collective time.

Sample Applications

At the end of the day, developers want to see the big picture. And the best way to show that is with working sample applications. I find that application code is the best way to communicate how everything in your API ties together and how it integrates with other systems.

A great example of this is sample code in Apple’s iOS Developer Library, which has an exhaustive selection of sample iOS apps organized by topic.

Add Personality

Reading API documentation isn’t exactly a thrilling roller coaster ride. But, you can at least add some personality and fun into your writing. Surprise your reader with funny examples and variable names other than foo.

This will at least prevent them from falling asleep.

Conclusion

The way to a developer’s heart is great documentation. And, great documentation requires a lot of investment. But, this investment is well worth it, and is just as important for a developer product as the API itself.

The other half of this is designing a great API in the first place. But, that will be the topic of another post.

Psst: If you love well designed APIs and teaching people about them, we’re hiring a Developer Evangelist at Parse.

James Yu
January 11, 2012

Archives

Categories

RSS Feed Follow us Like us