README.adoc

Table of Contents

• What you will build
• What you will need
• Create an iOS Project
• Create a ViewController
• Create a View
• Run the client
• Summary

This guide walks you through building a simple iOS client that consumes a Spring MVC-based RESTful web service.

What you will build

You will build an iOS client that consumes a Spring-based RESTful web service. Specifically, the client will consume the service created in Building a RESTful Web Servce.

The iOS client will be accessed through the iOS Simulator, and will consume the service accepting requests at:

http://rest-service.guides.spring.io/greeting

The service will respond with a JSON representation of a greeting:

{"id":1,"content":"Hello, World!"}

The iOS client will render the ID and content into a view.

What you will need

• About 15 minutes

• A Mac with OS X

• Xcode

• An internet connection

Create an iOS Project

Within Xcode, create a new project, using the "Single View Application" template. If you prefer, you can use the project in the initial folder and skip ahead to Create a ViewController. When you are finished, you can compare your code to the complete folder and Run the client.

Choose the following options for the new project. These are the same values used in the sample code. Note that iPhone is selected in the Devices drop down menu.

When the project is created, you will see that several files are added. To complete this guide, you will edit Main.storyboard, RestViewController.h, and RestViewController.m

Create a ViewController

The Model-View-Controller design pattern (MVC) is used extensively in iOS applications. As the name implies, a ViewController controls the view. When you created the project, a RestViewController was also created with an empty implementation.

First, modify the header file to include two properties, and a method signature.

Rest/RestViewController.h

link:complete/Rest/RestViewController.h[role=include]

The greetingId and greetingContent properties are UILabel types. These properties are declared with the type qualifier of IBOutlet. By declaring these as an IBOutlet, they can easily be connected to the view. Note how the fetchGreeting method is also declared with a type qualifier, in this case IBAction. Like the properties, this allows the method to be connected to a control in the view, for example a button.

Now update the fetchGreeting method body in the main class file.

Rest/RestViewController.m

link:complete/Rest/RestViewController.m[role=include]

There are three methods in the main class file, fetchGreeting, viewDidLoad, and didReceiveMemoryWarning. RestViewController inherits from UIViewController, and viewDidLoad and didReceiveMemoryWarning override the default implementations. viewDidLoad is modified so that fetchGreeting is called when the view is first loaded. didReceiveMemoryWarning is included for consistency with the default class template used when creating a new project, but otherwise it is unused in this guide.

The fetchGreeting method is where the HTTP request happens. It uses NSURLConnection to send an asynchronous request to the specified URL. This particular method makes use of an Objective-C construct called a "block". Blocks are similar to closures or lambdas in other programming languages. In this case, the block is passed to the completionHandler method parameter, meaning that on completion of the HTTP request the code within the block is executed.

If data is received and there is not an error when the HTTP request completes, NSJSONSerialization is used to read the data into an NSDictionary. Once the data is available in a dictionary, the "id" and "content" values are retrieved and assigned to the two labels that are defined in the header.

Create a View

Select the main.storyboard from the project navigator on the left side of the Xcode window. A Storyboard contains the layout for the view. Remember that you can always use the code in the initial folder if you have trouble with any of these steps.

Xcode provides a WYSIWYG editor for creating views. This editor is often referred to as Interface Builder because, historically, it was a separate application. You will now see the layout for the RestViewController. If you are viewing the layout from the initial folder, it includes a few labels for context. If you created a new project yours is empty.

In the bottom right corner of Xcode select and drag two Label objects to the storyboard layout. You can filter the list of objects using the field at the bottom. You will use the first label to display the Greeting’s ID, and the second for the Greeting’s content. If you created a new project follow these same steps to add three more labels (five total) to match the code from the initial folder.

Next, select and drag a Button object to the storyboard layout. This button will be used to refresh the content by making additional HTTP requests to the REST service.

Double-click one label and change it to "[id]", and the other to "[content]". This will be the placeholder text. These values will be replaced on successful completion of the HTTP request as described in "Create a ViewController" section. For new projects, modify the other three labels to read "Hello iOS", "The ID is", and "The Content is". Lastly, double-click the button to change it to read "Refresh".

Using the editor, you can move these labels around the storyboard to look similar to the following:

The content and id returned from the RESTful service may be longer than the label widths allow. Resize the width of the "[id]" and "[content]" labels to accommodate larger string values.

Now that you have all the UI objects on the storyboard, you can associate those objects with the properties in the RestViewController. The terminology used within Xcode is adding a new referencing outlet. Control-click the "id" label. Select the circle next to the "New Referencing Outlet" and drag it to the "Rest View Controller" icon. All the properties which are declared with the IBOutlet type modifier are listed. Select the greetingId to complete the association.

Repeat these same steps for the "content" label, this time selecting the greetingContent as the "New Referencing Outlet".

The final task is to add a referencing outlet for the button. In this case you will associate a button event with the fetchGreeting method in the RestViewController, which is declared with the IBAction type modifier.

Run the client

You can now run the app from Xcode. To do this, click the play button (triangle) in the top left corner of Xcode. It will open in the iOS simulator, where you see:

The ID value will increment each time you click the refresh button.

If the simulator window is too large for your display, you can reduce its size by selecting a scaled view of it:

Summary

Congratulations! You’ve just developed an iOS client that consumes a Spring-based RESTful web service.