It can be difficult to extract user entered data from a web view. This in turn raises the cost of destroying the web view when it is not visible in order to save memory and recreating it on demand. Behavior which may be much easier with native views. The overall memory overhead of loading a web view and its content may also be greater than that of an equivalent native UI.

In my case I also wanted to serve these forms from a generic API which would support multiple clients. While rendering a HTML form would have been convenient it would require at least a unique stylesheet per client in order to match the rest of the client’s design. Even more difficult would have been identifying and supporting different forms of navigation, element selection, and input on different devices. Selecting a list option might be best served by an action sheet with a UIPickerView on iOS devices and a drill-down selection screen which respects the hardware back button on Android devices. Text entry requires different markup to support different keyboard types on different devices. Detecting external keyboards vs onscreen keypads of different sizes may not be possible within a web view so repositioning content to accomodate the keyboard is difficult. Similarly it would be difficult for a client to choose to display a custom keyboard tailored to the type of entry required. Web views also do not have access to all of the native features of a device so a client displaying an HTML form cannot present the user with an option to complete an email input by selecting an address from their contact list.

Given all of those limitation I wanted to push responsibility for displaying these input forms onto the clients who would render an appropriate UI using their native view elements. This introduced its own set of tradeoffs. Native views with custom layout rules can be more expensive to develop than comparable web views. The api implementation would be limited to only those form elements supported by the clients and that list would need to be well defined rather than being able to supply effectively arbitrary HTML. Client side validation would also be more difficult that executing some server provided javascript on form submission.

Ultimately I settled on a Ruby DSL to define a JSON payload representing a form which was sent to the clients by the API’s Rails backend. Using a DSL allowed me to both produce an expressive language for defining these forms as views in my Rails application and also provided a convenient way to enforce that the resulting JSON was limited to a well defined set of possible values the clients would all be able to respond to appropriately. The result was a platform agnostic API response which could be used to generate different UI elements on different clients while returning a well defined set of data back to the API when the form was submitted. It was also flexible enough to allow server side updates to the required input fields and support a growing set of data served by this API without requiring client updates.

A form in one of the Rails views looked something like the following:

data_form do
  fieldset "Identity" do
    field :first_name, :label => "", :placeholder => "First Name"
    field :last_name, :label => "", :placeholder => "Last Name"
  end
  fieldset "Credentials" do
    field :email, :label => "", :placeholder => "Email Address", :type => :email
    field :password, :label => "", :placeholder => "Password", :type => "password"
    field :security_question, :label => "Security Question", :type => :select do
      User::security_questions.each { |q| option q, :label => q }
    end
    field :security_answer, :label => "", :placeholder => "Answer"
  end
  fieldset "Read & Agree" do
    field :terms_of_use, :label => "I agree to the Terms & Conditions.", :type => :checkbox do
      detail UserAgreement.current.terms, :label => "Terms & Conditions", :format => :html
    end
  end
  submit "Submit"
end

On an iOS device that form was then rendered as UINavigationController displaying a grouped UITableView with a section for each fieldset and a cell for each field. Each select field would push an additional table view onto the navigation stack containing a list of the field’s option element. Android clients presented a completely different view of the same form tailored to the device they were running on.

This designed worked well for the application I was working on but it certainly falls somewhere in the middle of a spectrum from completely native UIs to purely web view based UIs and may not be reasonable for many other applications. Taken too far this could grow into a poor reimplementation of HTML. Underutilized and this would be an unnecessarily over-engineered solution. However for a domain which demanded a flexible interface which could be updated from the server, support multiple clients, and provided all the interaction of a native UI I found this to be a great solution. Would you use something similar or what alternatives have you tried for your applications?

Once a request reaches my Rack/Rails stack it might still result in an error response if no matching route exists or if it fails validation. Some of these application level errors might map to HTTP status codes but not all of them. For example in the case of validation errors I want to return relevant messages to the client. In these cases I want to send a 200 response code to indicate that the response body can be expected to be well formatted. The client can then attempt to parse the response as JSON, identify that there was a validation error, and notify the user appropriately.

In a recent project my api responses looked something like this:


{
'error' : {
'type : "AStringDenotingTheErrorType",
'message' : "An error message appropriate for display to the user."
}
'data' : {
"attribute": value,
...
}
}


Mobile clients who maintain an offline cache of data might encounter validation errors as a result of being out of date with the server. I found it helpful to include an up to date representation of the model which failed validation in the error response. Much like rendering a form with validation errors, returning a model or other data along with a set of validation errors allows the client to make sure they are not submitting an out of date version of the resource.

For instance on an application which cached forms it received via an API submitting an old version of a form might result in a validation error. By returning the latest copy of the form with that validation error the client had an opportunity to update its cache and present the correct form the the user to make corrections and fill out new required fields.

A well designed API will communicate both application and protocol errors clearly to the client. It supplies the client with an appropriate level of information to correct errors when possible and saves the client from needing to guess what might have gone wrong with a failed request.

• REST still provides a nice clean way to organize our routes.
• XML and JSON are common data formats.
• Clients create sessions, often identified by a session id returned in a cookie.
• We can improve client performance and reduce server load by caching request responses, providing HTTP ETags and 304 responses, and appending asset ids to assets served via the rails stack.

However we also find a number of cases where our conventions do not match well with the needs and behavior of mobile clients.

Synchronous requests and redirects:

Synchronous requests on high latency wireless networks lead to a poor user experience as clients must wait for a response from the server before they can proceed. Unfortunately for us, redirects create synchronous requests. When a client encounters a redirect response it has waited for one full round trip to the server and must now wait for another round trip before it will have the information it needs to proceed. Similarly references to other resources including stylesheets or child objects cannot be loaded until the client has received the initial response containing those references.

Whenever a client needs to make multiple requests there is a reasonable chance that some of them will fail. This can become problematic as the client then needs to determine what to do with the partial set of data it has received. Should the client retry only the failed requests and hope that the rest of the data set is still up to date by the time they finish? Should the entire set of data be discarded because one portion could not be loaded? Can an incremental or partial set of results be shown to the user and still be meaningful?

For example

We might allow a user to sign into our API via a sessions/#create route and expose an authenticated user’s profile via a profile route. If we want to allow users to sign in and then be greeted by name (retrieved from their profile) we are forcing clients to either make a pair of synchronous requests before a user can move past the sign in screen or to display a reasonable interface when the users profile has not yet been retrieved.
If instead we were to return the user’s profile data as part of a successful sessions/#create response we could cut the perceived sign in time in half.

Returning deeply nested object graphs may present us with a new problem. Now we may need to join multiple models together to construct the response and generate an expensive query in the process. That’s not too bad, we’re pretty good at optimizing query times when they become a problem, but it also makes the resulting response harder to cache because we must invalidate that cache whenever any of the models included in that aggregate response change.

Sessions

On the web, sessions are well defined and we often use session cookies to store session identifiers. Mobile devices are not so simple; they are likely to gain and lose focus many times while a user is actively using the app. Every phone call, text message, switch to look at a mobile browser, and so on may force an iOS app into the background. As an app enters the background we could delete session identifiers and clear out any sensitive cached data, but we don’t know if the user will return immediately or in the far future. If we discard credentials aggressively we may force the user to re-authenticate after every interruption, a poor user experience, but if we do not we might expose those credentials to whomever next uses the app.
We might be able to conditionally clear out data from expired sessions when an app resumes but may also need to store it encrypted in order to prevent access to sensitive data while the app is not running.

Idempotent requests:

Mobile clients operate on unreliable network connections. As a result many of their network requests will fail somewhere along their route to our servers. Retrying failed requests should be an obvious initial solution when a request never reaches the server but what about when the acknowledgement of a request is lost on its way back to the client? Suppose our server received a request to create a new user account with a unique username and responded with some kind of 201 (created) response. Unfortunately the response never reached the client device, it eventually considers the request to have timed out and dutifully sends it again, eventually successfully. Now our server receives a second request to create an account with the same unique username and returns a validation error because that username is already taken!

It might be a better user experience if our server could identify duplicate requests from the same client and return the same response for all of them without applying duplicate changes to our model. In general it is beneficial for us if we can make all requests to our API idempotent, resulting in the same model state no matter how many times they are performed. Therefore we should prefer an update which sets a value to an update which increments that value or include enough information in each request (timestamps, sequence numbers, version numbers, and so on) to identify duplicate requests.

Closing thoughts:

Designing APIs for mobile clients presents some new problems which force us to reconsider some of our common practices as developers of web applications. Many of the conventions found in Rails are still valuable, but we need to respect the needs of our mobile clients and the network environment they operate in order to enable them to provide the best possible user experience.

Any app which contains code like
[viewController.view addSubview:someOtherViewController.view];
or
viewController.view.bounds = CGRectMake(50, 50, 100, 200);
or which loads a nib doing the equivalent is abusing UIViewControllers. Given time this will emerge as bugs or at least pain for developers continuing to work on the app.

What? How is that wrong?

The core problem, and surprise for too many developers, is stated in the “View Controller Programing Guide for iOS” in “About Custom View Controllers“:

Each custom view controller object you create is responsible for managing all of the views in a single view hierarchy. In iPhone applications, the views in a view hierarchy traditionally cover the entire screen, but in iPad applications they may cover only a portion of the screen. The one-to-one correspondence between a view controller and the views in its view hierarchy is the key design consideration. You should not use multiple custom view controllers to manage different portions of the same view hierarchy. Similarly, you should not use a single custom view controller object to manage multiple screens worth of content.

Essentially the rootViewController of the current UIWindow should be the only UIViewController with a visible view.

With multiple UIViewController’s views visible at once some of those controllers may not receive important messages like -viewWillAppear: or -didReceiveMemoryWarning. Additionally some of their properties like parentViewController and interfaceOrientation may not be set or updated as expected.

“Why won’t my UIViewController rotate with the device?” states this even more explicitly.

If you add an additional view controller’s UIView property to UIWindow (at the same level as your primary view controller) via the following:

[myWindow addSubview:anotherController.view];

this additional view controller will not receive rotation events and will never rotate. Only the first view controller added to UIWindow will rotate.

Now Apple is able to provide “container view controllers” like UINavigationController and UITabBarController which manage the presentation of other UIViewController’s views. Unfortunately to do so requires the use of private API calls which are not available for any app seeking approval for distribution in the App Store (discussed in more detail here: https://devforums.apple.com/message/310806#310806). We can come close but without a supported path for implementing custom container view controllers nesting UIViewControllers’ views will not give us all the behavior we expect from a UIViewController.

Isn’t close good enough?

Not really. We can implement a custom container view controller which sends messages like -viewWillAppear to its child view controllers but that only solves part of the problem.

• Without being able to rely on interfaceOrientation those child view controllers may never support rotation correctly.
  Since view controllers’ views are expected to fill the window views “behind” modal view controllers may not be drawn or may be unloaded while visible.
• Without properties like parentViewController or navigationController being set all of our child view controllers need to be aware of how they are being presented and the fact that they cannot rely on all the behavior they should be able to expect from inheriting from UIViewController.
• Child view controllers may not be properly inserted into the responder chain so they may never see events passed up the chain from their views.

With no public setters available for these properties or documentation of these behaviors there’s currently no way to resolve this situation (see this thread for further discussion: https://devforums.apple.com/message/365171#365171). Since there is currently no supported means of creating container view controllers those behaviors which do work now are not guaranteed to continue to function in future iOS updates and may vary between existing iOS versions.
By nesting UIViewControllers we create a UIViewController instance which cannot rely on the entire contract offered by UIViewController. A non-obvious and context specific problem for any developer working on the app in the future.

So what’s the alternative?

The “View Controller Programming Guide for iOS” at least suggests an alternative:

Note: If you want to divide a view hierarchy into multiple subareas and manage each one separately, use generic controller objects (custom objects descending from NSObject) instead of view controller objects to manage each subarea. Then use a single view controller object to manage the generic controller objects.

A controller does not necessarily have to be a subclass of UIViewController. We can create controller objects responsible for managing specific behaviors or portions of our view and have these controllers inherit from NSObject instead of from UIViewController. This allows you to break up your app’s controller logic into manageable classes with clear responsibilities while still following the limitations of UIViewController. This works well when you want to have different controllers manage different sections of a single view hierarchy.


@interface SampleController : NSObject {
}
@end


This is however an inadequate replacement for custom container view controllers which should be able to manage transitions between arbitrary UIViewControllers. Instead we have to either reinvent much of UIViewController’s behavior (-viewWillAppear: and -viewDidDisappear: style lifecycle methods, unloading and reloading of views on demand, transformation of views in response to device rotations) or abuse UIViewController and risk producing unstable apps.


@protocol ViewController
- (void)viewDidAppear:(BOOL)animated;
- (void)viewDidDisappear:(BOOL)animated;
- (void)viewWillAppear:(BOOL)animated;
- (void)viewWillDisappear:(BOOL)animated;
-(UIView *)view;
@end

@interface SampleContainerViewController : UIViewController {
}
- (void)setViewControllers:(NSArray *)viewControllers animated:(BOOL)animated;
@property(nonatomic, copy) NSArray *viewControllers;
@end


For now I have found that the best solution is to stay within the supported constraints of UIViewController and build custom non-UIViewController controllers as necessary. Have you found a better alternative, chosen to use UIViewControllers anyway, or avoided this problem entirely?

The fallacies of distributed computing

1. The network is reliable.
2. Latency is zero.
3. Bandwidth is infinite.
4. The network is secure.
5. Topology doesn’t change.
6. There is one administrator.
7. Transport cost is zero.
8. The network is homogeneous.

Fallacy #8: “the network is homogeneous”.

Mobile devices are something of an exception compared to web development; it is possible for an app to have a largely homogeneous network of users. Unfortunately assuming that the network is homogeneous still leads to problems on several levels.

Similarly to fallacy #6 not all networks will have the same configuration. For example some wifi networks will allow peer to peer communication between devices and some will not. Allowing a mobile app to communicate with other devices (ie synch with a desktop app) can therefore be difficult even if both are on the same network. TN2152 “Document Transfer Strategies” has an excellent overview of several techniques for communicating between devices or with remote services.

A web service might initially be designed for use only by iOS apps but it would be nice if adding apps for other device families later was not unnecessarily difficult. The service may therefore need to serve multiple data formats so its clients can choose to receive content as xml, json, or whatever they can easily parse. Binary and proprietary data formats may be difficult to parse on multiple devices.
For services based around a central server this shouldn’t be a serious problem as the server can serve content in each client’s preferred format and translate between them. For applications with direct peer to peer communication (ie using GameKit) connecting an iOS app to an Android app, or just handling clients using multiple versions of the same app, is more difficult.

The fallacies of distributed computing

1. The network is reliable.
2. Latency is zero.
3. Bandwidth is infinite.
4. The network is secure.
5. Topology doesn’t change.
6. There is one administrator.
7. Transport cost is zero.
8. The network is homogeneous.

Fallacy #7: “transport cost is zero”.

Arnon Rotem-Gal-Oz’s explanation of this fallacy points out two possible interpretations, both of which can be problematic mistakes.

First you can consider the cost of moving data between your application and the network interface. The performance impact of serializing objects or parsing data add a cost above and beyond the limitations of bandwidth and latency. Apple’s 2010 WWDC session 117 “building a server-driven user experience” for their comparison of the size and load time of data in xml, json, and plists (slide #40 & 41 at ~27:30). While the size of each format was similar the time required to parse the result varied tremendously; 812ms for xml, 416ms for json, 140ms for an ascii plist and only 19ms for a binary plist.

Secondly you can consider the cost of maintaining network services and infrastructure. How much load does each user place on your servers and what do they cost to run? How many concurrent requests can your servers actually handle and what does it cost to scale those systems? What does using your app cost your users who live with monthly data limits or pay on a per-kilobyte basis?

The fallacies of distributed computing

1. The network is reliable.
2. Latency is zero.
3. Bandwidth is infinite.
4. The network is secure.
5. Topology doesn’t change.
6. There is one administrator.
7. Transport cost is zero.
8. The network is homogeneous.

Fallacy #6: “there is one administrator”.

While you, as the developer, can control when your apps and servers are released and updated neither you nor anyone else can control the entire collection of devices which will be running your app. Your users will update their devices on different schedules or not at all. Leaving you with a range of different application version in the wild. For networked applications this may be problematic as you might have different application versions using different api versions to communicate with your server or with each other. I’ve found it helpful to introduce api versioning to a project as early as possible. There may not be any need to support multiple api versions immediately but having a strategy in place to move from api.example.com/1/ to api.example.com/2/ when you need to change an existing api call can make your next app release much smoother.
In addition to supporting users of different api versions apps also need to be able to handle upgrades locally. If you change the format for storing data on disk, or in core data, or in the keychain between application versions have a plan for migrating user’s existing data when they upgrade (or at least don’t crash trying to read an old data format). Your application will also need to handle users who upgrade from version 1 directly to version 3 without failing because you lost track of what changed in version 2.

As the administrators of their devices your users can change many of the other restrictions on your application’s environment as well. Only some of them will allow you to access their location. Only some of them will permit push notifications. Some of them will use parental controls to block access to Safari, the app store, or other applications.

The fallacies of distributed computing

1. The network is reliable.
2. Latency is zero.
3. Bandwidth is infinite.
4. The network is secure.
5. Topology doesn’t change.
6. There is one administrator.
7. Transport cost is zero.
8. The network is homogeneous.

Fallacy #5: “topology doesn’t change”.

WWAN connections use significantly more power than WiFi connections. This becomes important when working with long lived connections or streaming media. A connection established over the WWAN will keep that interface active even if a WiFi network becomes available. To avoid running both interfaces it is up to the app to close and re-establish any active connections on the newly available network interface. Use Apple’s Reachability example to monitor changes in available interfaces and react as necessary. Also take a look at Paul Danbold’s “Advanced networking” talk from the 2009 Tech Talk World Tour.

Those changes to the network are also likely to result in changes to the device’s available bandwidth and latency so apps which make decisions based on those characteristics may need to monitor their connections and adapt to changing conditions. Since apps which stream significant amounts of audio or video are required to use http live streaming they can automatically switch between available streams designed for higher or lower bandwidth connections as network conditions change.

The fallacies of distributed computing

1. The network is reliable.
2. Latency is zero.
3. Bandwidth is infinite.
4. The network is secure.
5. Topology doesn’t change.
6. There is one administrator.
7. Transport cost is zero.
8. The network is homogeneous.

Fallacy #4: “the network is secure”.

Any network service needs to consider security as part of its design and services built for use by iOS applications are no exception. All of the basic attacks a web service needs to consider still apply; session hijacking, stolen credentials, code injection, and so on. Securing a web service is a much larger topic but let’s consider a couple of areas specific to iOS client applications.

User’s devices are only as trustworthy as the users themselves. Anyone with a copy of your app can inspect both the contents of your application’s bundle and the traffic it sends. Don’t rely on your app storing a shared secret (credentials to access your web service, certificates, encryption keys, and so on) without revealing it to your users.

UDIDs are unfortunately a poor mechanism for user authentication. They are convenient as a unique identifier available without needing to walk users through any sort of account creation and I’ve worked on apps which use them as a temporary form of identification but they don’t work well as permanent identifiers. UDIDs are effectively user provided data and can be changed; either deliberately which might allow one user to masquerade as another or unintentionally when a user upgrades their device or installs an app on a second device. A UDID identifies a device, not a user.

Mobile devices are even more likely than general web traffic to be used on public access points and networks which can easily include malicious users. Any data your app sends in the clear can be read by other members of the network. If you or your users consider that data sensitive it really needs to be sent over an encrypted connection. Apple provides the Advanced URLConnection sample application which demonstrates establishing connections using http basic auth, and certificates (including self-signed certificates if you want to issue your own for your web services).
As a simplistic example a NSURLConnection can support https requests with the addition of just two additional delegate methods.

- (void) httpsConnection {
    self.connection = [NSURLConnection connectionWithRequest:[NSURLRequest requestWithURL:[NSURL URLWithString:@"https://encrypted.google.com/"]] delegate:self];
    [self.connection start];
}

-(BOOL) connection:(NSURLConnection *)connection canAuthenticateAgainstProtectionSpace:(NSURLProtectionSpace *)protectionSpace {
    return [protectionSpace authenticationMethod] == NSURLProtectionSpaceHTTPS;
}

-(void) connection:(NSURLConnection *)connection didReceiveAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge {
    if ([challenge previousFailureCount] == 0) {
        if ([challenge proposedCredential] == nil) {
            NSURLProtectionSpace *protectionSpace = [challenge protectionSpace];
            SecTrustRef trust = [protectionSpace serverTrust];
            SecTrustResultType trustResult;
            SecTrustEvaluate(trust, &trustResult);
            if (trustResult == kSecTrustResultProceed) {
                NSURLCredential *credential = [NSURLCredential credentialForTrust:trust];
                [[challenge sender] useCredential:credential forAuthenticationChallenge:challenge];
            }
            else {
                [[challenge sender] cancelAuthenticationChallenge:challenge];
            }
        }
        else {
            [[challenge sender] cancelAuthenticationChallenge:challenge];
        }
    }
    else {
        [[challenge sender] cancelAuthenticationChallenge:challenge];
    }
}

The fallacies of distributed computing

1. The network is reliable.
2. Latency is zero.
3. Bandwidth is infinite.
4. The network is secure.
5. Topology doesn’t change.
6. There is one administrator.
7. Transport cost is zero.
8. The network is homogeneous.

Fallacy #3: “bandwidth is infinite”.

Bandwidth is not unlimited and it is not free, this has implications beyond “downloading lots of data takes longer”.

1. Apps over 20MB cannot be downloaded over cellular networks: see the App store approval guidelines.

2. If your app delivers video over cellular networks, and the video exceeds either 10 minutes duration or 5 MB of data in a five minute period, you are required to use HTTP Live Streaming. (Progressive download may be used for smaller clips.)

   If your app uses HTTP Live Streaming over cellular networks, you are required to provide at least one stream at 64 Kbps or lower bandwidth (the low-bandwidth stream may be audio-only or audio with a still image).

   From the Streaming Media Guide.

3. Audio streaming content over a cellular network may not use more than 5MB over 5 minutes

   From the App store approval guidelines.

Many users do not have unlimited data plans so your app’s total bandwidth use while on a mobile network may be a concern.

Since the network is not reliable large requests, which take longer to complete, are sometimes going to fail as a network connection is interrupted. If your app cannot resume those connections you risk always transferring the first 80% of the data, losing the connection, and starting again from the beginning.

Users are also unreliable; they will close or background the app while you are trying to transfer data for them.

Testing bandwidth
I use Charles to throttle network bandwith to test apps using low bandwith connections during development.
The Settings app provides an easy tool for measuring cellular bandwidth use if your app behaves differently while using the WWAN; look in Settings -> General -> Usage.