Introduction
In this tutorial series, we will create an iOS application that will leverage Swift's networking
layer to query a custom-built web service. First, we'll build a RESTful API in PHP from the bottom up and host it on our local machine. Then we'll craft an iOS Swift application to consume the content provided by the service, and present it to the end user in a collection view. The series is intended for people who have some degree of programming experience, but who have not yet obtained much practical knowhow on building an everyday, real-world, user-facing, mobile application.
A typical use case for
mobile applications requires the consumption of content that is
hosted on a web server. For successful mobile app development, this
means that you not only need to know how to build an application that
consumes web content, but also to have a high level understanding (at
the very least!) of how a web service actually delivers content to
your mobile application.
This is important because you will encounter network related errors during your development cycle. And if you don't have at least a basic understanding of the web service that your are trying to communicate with, then you cannot be sure where the errors are originating from. In addition, you will likely also be asked, at work or by your own clients, to begin writing a mobile application that relies on a web service that has not been built yet! (This actually happens way too often!) In such cases, you can write your own temporary web service that delivers mock data to your application, if you know how to build one. Although there are other ways of delivering such mock data, this can be just as useful.
This is important because you will encounter network related errors during your development cycle. And if you don't have at least a basic understanding of the web service that your are trying to communicate with, then you cannot be sure where the errors are originating from. In addition, you will likely also be asked, at work or by your own clients, to begin writing a mobile application that relies on a web service that has not been built yet! (This actually happens way too often!) In such cases, you can write your own temporary web service that delivers mock data to your application, if you know how to build one. Although there are other ways of delivering such mock data, this can be just as useful.
In this article, we'll provide an overview of the project, and then work through the preliminary steps for running the web service on our local machine. In the following articles, we'll build out the PHP script that will execute the API, and finally construct our Swift application to query the service and return the relevant data to the end user.
The ABCs of APIs
What is an API and how will our Swift
application interface with it? API stands for Application Programming
Interface. A simple web search for 'API' will return many definitions with
various types of descriptions and creative examples. I like to think
of an API as a real object.
 |
| Source |
Since the internet is a series of pipes and tubes, our API will provide an interface to a plumbing supply inventory. Let's call our API the Mario
Interface. Mario works at the front desk of a plumbing supply house
called Super PHPlumbing Bros Inc. Mr. Swift is a plumber who needs
some supplies to rescue a local potentate's daughter from the
clutches of an invading warlord.
Mr. Swift finds PHPlumbing and walks up
to the counter where he encounters Mario. Mr. Swift tells Mario that
he would like some piping, mushrooms and a
wrench. Mario says, "No problem, but first I need you to know
exactly what you need," and hands Mr. Swift two forms.
Each form is titled with the company's
name. Below the title, there are several check boxes, but only one may be
checked per form. The relevant check boxes are: Piping/Fittings and
Plumbing Tools. Below that is a description field for the requested
items along with their quantity.
Once completed, Mr. Swift hands the
forms to Mario, who then passes them along to his employees, local
Toads from the Mushroom Kingdom, who are tasked to assist him. The
Toads find the relevant items, bring them out and place them on the
counter.
If at any point during this process
there was a problem retrieving Mr. Swift's supplies, the Toads are
responsible for reporting these errors up the chain of command, from
the assistants up to Mario and terminating at Mr. Swift.
In our analogy, Mr. Swift is the
client (our iOS application) in need of content or plumbing supplies.
Super PHPlumbing Bros Inc. is the store or website that has the
supplies or content that Mr. Swift is looking for. The form for
getting supplies is the actual url (location of content) that is used
to find and retrieve the content. And Mario, along with the Toads,
comprise the API.
APIs, and people like Mario, are needed to maintain
a system of flow control structures that are necessary to efficiently
run the business logic of the operation. Can you imagine a plumbing
supply house that had no control structures like forms and employees
to manage its everyday workflow? The princess would be doomed.
In this tutorial series, we'll construct a RESTful API in PHP to serve up an inventory of plumbing tools and supplies, and then build a custom Swift app to interface with the API and serve that inventory to the end user. For now, let's get our local server up and running.
Setting Up the Local Server
Unfortunately, the PHP file
that will serve our API will not execute on its own. A service is
required to interpret and execute our PHP script. We therefore need
to set up a place on our local machine to host our Super PHPlumbing
Bros. supply house. One of the easiest ways to get a server up and running on a
Mac is with MAMP. Once you've downloaded MAMP,
you can run the package by double clicking it.
After the
package mounts, follow the instructions to install the software.
Once installed, navigate to your Applications folder and start MAMP.
You will be prompted with several initialization screens. Once MAMP
is installed, start the server my clicking the START button in the
top right corner of the application window.
The tiny
box to the right of the word Apache should turn green if everything
went smoothly. This means that your server is up and running! Now start a
new session of Safari, and in the url field type the following
address: http://localhost:8888
You should see a similar screen to the following, which indicates that all is in working order:
.htaccess
Remember, any file name that begins with a period “.” is a system file and is hidden by default. To view hidden files, you can use the "ls -a" command in a terminal. To view hidden files in Finder, you can follow the instructions here.
File Structure
Navigate to the folder that contains your .htaccess file. For me, it's /Applications/MAMP/htdocs, and create three folders with the following names: v1, v2, assets. More on these folders later, but for now, your folder structure should more or less look like the following:
Moving Forward
With that, we're all set to go! In the next segment of the tutorial we'll build our RESTful API in PHP, so let's take the plunge. Or, if you want to skip ahead, follow the link to the tutorial segment on building our Swift client application.
This project can be found on GitHub.
Index
Introduction
Introduction and Overview: From the Back End API to the End User Application
The Web API
Building a RESTful API in PHP, Part 1
Building a RESTful API in PHP, Part 2
The Swift Client App
Networking in Swift: Building the Swift Client, Part 1
Networking in Swift: Building the Swift Client, Part 2
Networking in Swift: Building the Swift Client, Part 3
Networking in Swift: Building the Swift Client, Part 4
Networking in Swift: Building the Swift Client, Part 5
This tutorial was authored by Stefan Agapie, a Senior iOS Software Engineer, and adapted for the present piece.
