How to Write an iOS App That Uses a Web Service

Ray Wenderlich

This post is also available in: Spanish

Web Services + iPhone Apps Rule!

Web Services + iPhone Apps Rule!

As an iOS developer, you often need to use a web service from your app.

Sometimes you need to use a web service that someone else has written, and sometimes you need to use one of your own!

In this tutorial, you’ll get hands-one experience with using web services, by writing an iOS app that communicates with a simple web service that allows you to redeem promo codes to unlock extra content.

This tutorial is the second and final part of a two part series on custom web services. If you are curious how to develop the web service yourself, check out the first part of the series for full details!

You don’t necessarily have to set up the web service yourself for this tutorial – you can use the one I’ve already set up if you’d like.

This tutorial assumes you have basic familiarity with programming for iOS. If you are new to iOS development, you may wish to check out some of the other tutorials on this site first.

The Choice

This tutorial requires you to create a new View-based application and integrate three frameworks into it: the JSON framework, ASIHTTPRequest, and MBProgressHUD. You also have to make a basic UI for the app so the user can enter in a code to redeem.

But that’s a lot of work, so I thought we’d start this tutorial out with a choice. Are you like this guy?

"F that!" guy

If so, then just download this starter project with the libraries pre-integrated and the UI pre-made and skip the next two sections :]

Otherwise, read on DIYer! :]

Do It Yourself!

If you want to create everything yourself, start up Xcode and go to File\New\New Project, select iOS\Application\View-based Application, and click Next. Enter PromoTest for the Product Name, click Next, and save it somewhere.

To add the JSON framework, first download it from its github page. Once you have it downloaded, right click your PromoTest project entry in groups and files, select New Group, and name the new group JSON. Then drag all of the files from the JSON\Classes directory (JSON.h and several others) into the new JSON group. Make sure “Copy items into destination group’s folder (if needed)” is selected, and click Finish.

To add ASIHTTPRequest, first download it. Once you have it downloaded, right click your PromoTest project entry in groups and files, select New Group, and name the new group ASIHTTPRequest. Then drag all of the files from the ASIHTTPRequest\Classes directory (ASIAuthenticationDialog.h and several others, but IMPORTANT! don’t add the subfolders such as ASIWebPageRequest, CloudFiles, S3, and Tests.) into the new ASIHTTPRequest group. Make sure “Copy items into destination group’s folder (if needed)” is selected, and click Finish.

Also repeat this for the two files in ASIHTTPRequest\External\Reachability, as these are dependencies of the project.

To add MBProgressHUD, first download it. Once you have it downloaded, right click your PromoTest project entry in groups and files, select New Group, and name the new group MBProgressHUD. Then drag MBProgressHUD.h and MBProgressHUD.m into the new MBProressHUD group. Make sure “Copy items into destination group’s folder (if needed)” is selected, and click Finish.

The last step is you need to link your project against a few required frameworks. To do this, click on your PromoTest project entry in Groups & Files, click the PromoTest target, choose the Build Phases tab, and expand the Link Binary with Libraries section. Click the plus button in this section, and choose CFNetwork.framework. Then repeat this for SystemConfiguration.framework, MobileCoreServices.framework, and libz.1.2.3.dylib.

Framework Dependencies in Xcode 4

Compile your project just to make sure you’re good so far, and now we’re back to the fun stuff!

Implementing the Interface

Let’s make a quick and simple interface to test this web service. As a refresher, the web service takes three parameters:

  1. rw_app_id: The unique identifier for the app. If you’ve been following along with the previous tutorial, there should be only one entry so far, App ID #1.
  2. code: The code to attempt to redeem. This should be a string that’s entered by the user.
  3. device_id: The device ID that is attempting to redeem this code. We can get this with an easy API call.

So basically, all we need is a text field for the user to enter the code (they’ll tap “Go” on the keyboard to start the redemption process), a label for the text field, and a text view to write the result out to.

So click on PromoTestViewController.xib, bring up the Object library by selecting the third tab in the View toolbar (Utilities) and selecting the third tab in the library toolbar (Object library), as shown in the screenshot below.

Object Library in Xcode 4

From the Object library, drag a UILabel, UITextField, UITextView into the main view. Double click the UILabel and change the text to read “Enter promo code:”. Then double click the text view and delete all the text inside, and optionally change the background color of the UITextField to clear in the Attributes Inspector.

You also may find it useful to go to Editor\Canvas\Show Bounds Rectangles so you can see the bounds of the text view.

At this point your layout should look similar to the screenshot below:

Interface Builder Layout in Xcode 4

Next, you need to set the File’s Owner as the Text Field’s delegate so you can get a callback when the return button is clicked on the keyboard. To do this, control-click on the Text Field, and drag a line from the delegate entry to the File’s Owner.

Also, you need to connect the text view to an outlet so you can set it later. To do this in the cool new Xcode 4 way, first turn on the Assistant Editor (the second button in the Editor tab) and make it show up on the bottom with View\Assistant Layout\Assistant Editors on Bottom. Make sure it’s set to Automatic and that PromoTestViewController.h is visible.

Then select the Text View and control-drag a line from the text view down to right above the @end keyword, set Connection tou Outlet, the Name to textView, and click Connect, as you can see in the screenshot below.

Connecting an Outlet with the Assistant Editor in Xcode 4

At this point Xcode will automatically create a textView property and instance variable for you.

Finally, open PromoTestViewController.h and mark the class as implenting UITextFieldDelegate as follows:

@interface PromoTestViewController : UIViewController <UITextFieldDelegate> {

Then switch to PromoTestViewController.m and implement textFieldShouldReturn as follows:

- (BOOL)textFieldShouldReturn:(UITextField *)textField {
    NSLog(@"Want to redeem: %@", textField.text);
    return TRUE;
}

Compile and run your app, tap the text field, enter a code, and tap the return button, and you should see a message in your console output similar to the following:

2011-03-28 15:37:05.342 PromoTest[44350:207] Want to redeem: test

OK – all the setup is done, and you’re ready to start communicating with the web service!

Communicating with the Web Service

If you’ve grabbed the starter project and skipped ahead, here’s where you should pick back up! Otherwise, good progress so far DIYer! :]

To redeem the promo code, we need to to send a POST to our web service’s with three parameters: the app id, the code to redeem, and the device ID.

The good news is sending a POST is extremely easy with ASIHTTPRequest. You simply:

  • Create a new instance of ASIFormDataRequest and specify the URL
  • Use the setPostValue method to specify each parameter
  • Set the view controller as the delegate of the request, and then call startAsynchronous to start the request in the background
  • When it’s done, either requestFinished or requestFailed will be called on the view controller
  • requestFinished will be called even if the web server responds with an error code. So there you need to check for success or failure…
  • And if success, parse the response string as JSON!

Let’s see what this looks like. First add the following imports to the top of the file:

#import "ASIHTTPRequest.h"
#import "ASIFormDataRequest.h"
#import "JSON.h"

Then replace textFieldShouldReturn with the following:

- (BOOL)textFieldShouldReturn:(UITextField *)textField {
    NSLog(@"Want to redeem: %@", textField.text);
 
    // Get device unique ID
    UIDevice *device = [UIDevice currentDevice];
    NSString *uniqueIdentifier = [device uniqueIdentifier];
 
    // Start request
    NSString *code = textField.text;
    NSURL *url = [NSURL URLWithString:@"http://www.wildfables.com/promos/"];
    ASIFormDataRequest *request = [ASIFormDataRequest requestWithURL:url];
    [request setPostValue:@"1" forKey:@"rw_app_id"];
    [request setPostValue:code forKey:@"code"];
    [request setPostValue:uniqueIdentifier forKey:@"device_id"];
    [request setDelegate:self];
    [request startAsynchronous];
 
    // Hide keyword
    [textField resignFirstResponder];
 
    // Clear text field
    textView.text = @"";    
 
    return TRUE;
}

If you’ve set up your own web service following the previous tutorial, you should replace the URL with wherever you put your web service.

As you can see – very simple, following the steps outlined above. Finally, implement the requestFinished and requestFailed callbacks to log out the results:

- (void)requestFinished:(ASIHTTPRequest *)request
{    
 
    if (request.responseStatusCode == 400) {
        textView.text = @"Invalid code";        
    } else if (request.responseStatusCode == 403) {
        textView.text = @"Code already used";
    } else if (request.responseStatusCode == 200) {
        NSString *responseString = [request responseString];
        NSDictionary *responseDict = [responseString JSONValue];
        NSString *unlockCode = [responseDict objectForKey:@"unlock_code"];
 
        if ([unlockCode compare:@"com.razeware.test.unlock.cake"] == NSOrderedSame) {
            textView.text = @"The cake is a lie!";
        } else {        
            textView.text = [NSString stringWithFormat:@"Received unexpected unlock code: %@", unlockCode];
        }
 
    } else {
        textView.text = @"Unexpected error";
    }
 
}
 
- (void)requestFailed:(ASIHTTPRequest *)request
{    
    NSError *error = [request error];
    textView.text = error.localizedDescription;
}

This simply checks for the error codes that we expect from our web service, and prints a message for each. Or if it’s succcessful, parses the JSON with the JSON framework, and checks the unlock code. Here is where you could grant the user with whatever special content you might want to give them in your app.

Compile and run your project, and you should see something like the following:

The cake is a lie!

Adding a Progress HUD

The app works so far, but when you’re running a task in the background like this it’s often nice to let the user know what’s going on. This is nice and easy with MBProgressHUD, so let’s quickly add it in:

// Add at the top of the file
#import "MBProgressHUD.h"
 
// Add right before return TRUE in textFieldShouldReturn
MBProgressHUD *hud = [MBProgressHUD showHUDAddedTo:self.view animated:YES];
hud.labelText = @"Redeeming code...";
 
// Add at start of requestFinished AND requestFailed
[MBProgressHUD hideHUDForView:self.view animated:YES];

Compile and run your code, and this time a nice progress indicator should appear while the request is running!

Promo Code System: My Experience

Now as promised, I’d like to share my experience using this promo code system in Wild Fables with you guys!

I set up two codes for Wild Fables – one to unlock a single fable (of the user’s choice), and one to unlock all fables. I set up the first one so I could give out codes to friends & family to give them a little extra taste of Wild Fables, and I set up the second one so I’d have a way to give out full access to Wild Fables to professional app reviewers.

One of my favorite things about this system is it allows for unlimited codes. Which was great as 100 people used a code I gave out on Twitter alone (thanks again for checking it out and all the RTs guys, you rule!)!

I also put some codes in some threads on some various iOS forums, our mailing list for Razeware, our Facebook pages, etc. I made a separate code for each place I gave out the code, which is nice because it let me track where people actually cared about the post & used codes, and where people were more like the picture earlier in this tutorial ;]

People redeemed the codes most often on Twitter or the Cocos2D forums (which makes sense, as my friends such as yourself hang out there), then on the Razeware mailing list (which also makes sense, since if people subscribe to that they must be interested in our products). Forum-wise, Reddit came up on top, then the iPad Forums, MobileRead, MacRumors, and TouchArcade were the best in that order.

Another amusing thing was sometimes I’d get emails from “reviewers” asking for a promo code to redeem my app, so of course I’d send them a custom code. But these “reviewers” would also include a pitch to try to get me to advertise on my site. Looking at the redemption table, I can see that several of them didn’t even bother to redeem the code, so I guess their real reason to email me was to get ad revenue, so beware! :]

As far as drawbacks go, as some people noticed the “unlock” is implemented basically by saving data to the file system, so it doesn’t work across all devices like in-app purchases do. You can implement this by creating a login system or such, but that was overkill for what I wanted to do.

So that’s it for my experience! Let me know if you have any further questions.

Where To Go From Here?

Here is a sample project with all of the code we’ve developed in the above tutorial.

Now that you have first-hand experience creating both a simple web service and an app that communicates with it from scratch, you can take the ideas here and create your own web services that do anything you need for your app!

If you have any questions about communicating with a web service from an iPhone app, questions about the promo code system, or advice for others in this matter, please join the forum discussion below!

Ray Wenderlich

Ray is an indie software developer currently focusing on iPhone and iPad development, and the administrator of this site. He’s the founder of a small iPhone development studio called Razeware, and is passionate both about making apps and teaching others the techniques to make them.

When Ray’s not programming, he’s probably playing video games, role playing games, or board games.

User Comments

158 Comments

[ 1 , 2 , 3 , 4 , 5 , 6 , 7 , 8 , 9 , 10 , 11 ]
  • See if the debug console gives you some additional messages prior to the "Terminating app" message.

    I'm thinking that you are using testView in your code, when you should be using textView.
    Richard Caseyrcasey
  • Have you considered updating this tutorial to be ARC compliant and use MKNetworkKit since ASIHTTPRequest is no longer being supported? I used this tutorial to see how to create my own server side app and client side (IOS) app but since it was ARC, it wouldn't work with ASIHTTPRequest, so I found MKNetworkKit and converted to that. The conversion was pretty straightforward. The downside for MKNetworkKit is that the documentation is pretty thin. He relies on comments in the headers to document it and has some demos and since the framework is lightweight and easy to use, it isn't too bad, but it took a while to figure out some of his terms.
    macinsmith
  • i think this article very usefull but now ios support json. this article to be updated.
    isko
  • Hi I am having "Unexpected error" return instead of "The cake is a lie!" after inputting "test" as promo code.
    Xcode noob
  • Hi i have Xcode 4.6.2 and i am having this error "llvm-gcc-4.2 failed with exit code 1]"...pls advice
    slowrall
  • Hi

    Can you guide me on this problem with webservice. I am making an app which would have a corresponding desktop application. How can I avoid checking the webservice if theres new data which desktop application is trying to send to it. Is there a way to push data from webservice to iOS?
    Yogee1105
  • isko wrote:i think this article very usefull but now ios support json. this article to be updated.


    I went through a updated this tutorial. This is updated to include built-in JSON parsing via NSJSONSerialization (added in iOS 5) and built-in HTTP POST via NSURLSession (added in IOS 7) which replace the JSON and the ASIHTTPRequest frameworks in this tutorial.

    The entire project can be grabbed from my github if you want at https://github.com/jbutewicz/PromoTest

    Below is just the code for the ViewController.m

    Code: Select all
    //
    //  ViewController.m
    //  PromoTest
    //
    //  Created by Joseph Butewicz on 11/17/13.
    //  Copyright (c) 2013 Joseph Butewicz. All rights reserved.
    //

    #import "ViewController.h"
    #import "MBProgressHUD.h"

    @interface ViewController ()

    @end

    @implementation ViewController

    - (BOOL)textFieldShouldReturn:(UITextField *)textField {
       
        // Get device unique ID
        UIDevice *device = [UIDevice currentDevice];
        NSString *uniqueIdentifier = [[device identifierForVendor] UUIDString];
       
        // Store code from UI
        NSString *code = textField.text;
       
        // Hide keyword
        [textField resignFirstResponder];

        // Clear text field
        _textView.text = @"";
       
        // Show progress window
        MBProgressHUD *hud = [MBProgressHUD showHUDAddedTo:self.view animated:YES];
        hud.labelText = @"Redeeming code...";
       
        // Start NSURLSession
        NSURLSessionConfiguration *defaultConfigObject = [NSURLSessionConfiguration defaultSessionConfiguration];
        NSURLSession *defaultSession = [NSURLSession sessionWithConfiguration: defaultConfigObject delegate: nil delegateQueue: [NSOperationQueue mainQueue]];
       
        // POST parameters
        NSURL *url = [NSURL URLWithString:@"http://www.wildfables.com/promos/"];
        NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:url];
        NSString *params = [NSString stringWithFormat:@"rw_app_id=1&code=%@&device_id=%@", code, uniqueIdentifier];
        [urlRequest setHTTPMethod:@"POST"];
        [urlRequest setHTTPBody:[params dataUsingEncoding:NSUTF8StringEncoding]];
       
        // NSURLSessionDataTask returns data, response, and error
        NSURLSessionDataTask *dataTask =[defaultSession dataTaskWithRequest:urlRequest
                                                          completionHandler:^(NSData *data,
                                                                              NSURLResponse *response,
                                                                              NSError *error) {
                                                             
                                                              // Remove progress window
                                                              [MBProgressHUD hideHUDForView:self.view animated:YES];

                                                              // Handle response
                                                              NSHTTPURLResponse* httpResponse = (NSHTTPURLResponse*)response;
                                                              NSInteger statusCode = [httpResponse statusCode];
                                                              if(error == nil) {
                                                                 
                                                                  if (statusCode == 400) {
                                                                      _textView.text = @"Invalid code";
                                                                  } else if (statusCode == 403) {
                                                                      _textView.text = @"Code already used";
                                                                  } else if (statusCode == 200) {
                                                                     
                                                                      // Parse out the JSON data
                                                                      NSError *jsonError;
                                                                      NSDictionary *json = [NSJSONSerialization JSONObjectWithData:data
                                                                                                                           options:kNilOptions
                                                                                                                             error:&jsonError];
                                                                     
                                                                      NSString* unlockCode = [json objectForKey:@"unlock_code"];
                                                                     
                                                                      // JSON data parsed, continue handling response
                                                                      if ([unlockCode compare:@"com.razeware.test.unlock.cake"] == NSOrderedSame) {
                                                                          _textView.text = @"The cake is a lie!";
                                                                      } else {
                                                                          _textView.text = [NSString stringWithFormat:@"Received unexpected unlock code: %@", unlockCode];
                                                                      }
                                                                     
                                                                  } else {
                                                                      _textView.text = @"Unexpected error";
                                                                  }
                                                             
                                                              } else {
                                                                  _textView.text = error.localizedDescription;
                                                              }
                                                                 
                                                          }];

        [dataTask resume];

        return TRUE;

    }

    - (void)viewDidLoad
    {
        [super viewDidLoad];
       // Do any additional setup after loading the view, typically from a nib.
    }

    - (void)didReceiveMemoryWarning
    {
        [super didReceiveMemoryWarning];
        // Dispose of any resources that can be recreated.
    }

    @end
    jbutewicz
  • Great tutorial Ray!!

    Do you have something similar for consuming a WCF SOAP web-serice? My project involves sending a request with one parameter (in addition to the standard username/pwd etc.) and getting a response back with data.

    I tried doing something similar to http://iphonedevsdk.com/forum/iphone-sd ... rvice.html but being a complete beginner wasn't able to understand much from it.

    Your step by steps are on the other hand extremely helpful.

    Thanks,
    ArunSharma
[ 1 , 2 , 3 , 4 , 5 , 6 , 7 , 8 , 9 , 10 , 11 ]

Other Items of Interest

Ray's Monthly Newsletter

Sign up to receive a monthly newsletter with my favorite dev links, and receive a free epic-length tutorial as a bonus!

Advertise with Us!

Hang Out With Us!

Every month, we have a free live Tech Talk - come hang out with us!


Coming up in May: Procedural Level Generation in Games with Kim Pedersen.

Sign Up - May

Coming up in June: WWDC Keynote - Podcasters React! with the podcasting team.

Sign Up - June

Vote For Our Next Book!

Help us choose the topic for our next book we write! (Choose up to three topics.)

    Loading ... Loading ...

Our Books

Our Team

Tutorial Team

  • Ali Hafizji

... 55 total!

Editorial Team

  • John Clem

... 22 total!

Code Team

  • Orta Therox

... 1 total!

Translation Team

  • Takeichi Kanzaki Cabrera
  • Dave Harry

... 38 total!

Subject Matter Experts

  • Richard Casey

... 4 total!