My iOS App Creation Process — Part 5
Continuing my series, I now focus on interacting with the Flickr.com API to retrieve a photostream and decode the result into individual Flickr photos for consumption in my iOS app. In this article, I describe the use of the Flickr API, JSON modeling, and OAuth authentication.
Flickr API Background
Flickr’s Application Programming Interface (API) is the official means for programmers to interact with Flickr.com. It provides the programmer with a standardized, fully supported set of methods that return data from Flickr.com in a documented, standard format.
The Flickr API uses an Endpoint URL for each method combined with security keys the programmer requests when registering to use the API. Combining these components with the specific API method and parameters, the API then returns the requested data in a predetermined format for consumption by the programmer. Flickr offers an introduction to their API here.
Flickr API Basic URLs
The basics of the Flickr API URLs are in my FlickrAPI.swift file:
Flickr API Methods
There are many methods offered by the Flickr API. The following is a listing of the Flickr API methods I utilize in the iOS app:
The first three endpoints (lines 2–4 above) display the photostreams based on the photo category picker selection on the MainScreen “Flickr Photos” tab. The MainScreen “Manage Favorites” tab uses the fourth endpoint (line 5). The PhotoScreen uses the last two endpoints (lines 6–7) to either add or remove a photo from the Favorites list on the user’s Flickr account. Refer to Part 4 of the series for more information on the app screens.
Flickr API Responses
When calling a method, the API responds in a specific format and content (e.g., a collection of Photos, a response code indicating the method’s success/failure, etc.). Based on our iOS app and the selected methods, the following are the modeled responses:
FlickrPhotosInfoResponse.swiftrepresents the API response to the methods in lines 2–5 in theEndPoint.swiftfile. These calls return basic information along with the collections of photos. (Refer toFlickr_API_Result.jsonfile in the next section for more context.)
2. FlickrPhotosResponse.swift represents the actual collection of photos within the FlickrPhotosInfoResponse results. (Refer to the Flickr_API_Result.json file in the next section for more context.)
3. FlickrFavoritesResponse.swift represents the API method’s success/failure to add or remove a photo to/from a user’s Favorites collection on Flickr.com.
API Errors
When calling an API, you need to account for errors that may occur. There are two error types to consider:
- The network call to the API fails to return any data (e.g., network error)
- The API returns data, but the returned data doesn’t match the expected format/content (e.g., parsing error)
Given a basic understanding of how to interact with the Flickr API, we move on to JSON modeling the API results.
JSON Background
JSON (JavaScript Object Notation) is an open standard file format and data interchange format that uses human-readable text to store and transmit data objects consisting of attribute-value pairs and array data types (or any other serializable value). Since Flickr supports JSON-formatted data, I use Swift’s Codable protocol to decode the Flickr data.
Step 1: Understand the JSON-formatted data
The very first step is understanding the JSON-formatted data that Flickr returns. Using Postman, I constructed and executed a Flickr API call using the flickr.interestingness.getList method to retrieve the first three (3) photos in the Interesting photostream:
https://www.flickr.com/services/rest/?method=flickr.interestingness.getList&api_key=REPLACEWITHAPIKEY&extras=date_taken,height_z,width_z,views,url_z,latitude,longitude,accuracy,license,geo&format=json&nojsoncallback=1&per_page=3The returned JSON-formatted data appears below:
Examining the returned data structure, we see a tag called “photos” (line 2), representing the method is returning a collection of photos. The image collection is tagged with “photo” and an array’s opening bracket on line 7. Each photo appears within the left-brace/right-brace pair (lines 8–30, lines 31–53, and lines 54–82). The closing bracket of the photo array appears at line 83. Examining each photo, we see the specific data elements requested and returned (e.g., id, owner, title, datetaken, etc.).
Just as important as examining the structure of the JSON-formatted results, one must also understand the breadth of the data returned within the specific data elements to choose the proper data types in the Swift Codables. For example, the “id” attribute is returned as a String while the “height_z” attribute is returned as an Int. Additionally, specific attribute values may refer to other JSON structure objects such as “license” requiring further analysis of JSON results.
Further examining photo attributes, you may notice the geolocation data (tags: latitude, longitude, and accuracy) is returned as zeros (Int) when there is no valid data, but it is returned as Strings when there is valid data. I consider this poor API practice because it complicates the decoding of the JSON results. I found a very workable solution to implement a CodableValue property wrapper that handles multiple value types for the same attribute.
Step 2: Build the Swift codable models to represent the JSON-formatted data
Developing the codable data model is relatively straightforward once you understand the attributes and their corresponding data types. The programmer should take care to use Swift-like names for the data elements in the resulting Codable model. The CodingKeys enum “map” the JSON attribute names to the Swift attribute names. The following Photo.swift is the model for a Flickr photo based on the attributes anticipated for the app and available via the API:
The license attribute is a separate data model in Flickr, so I model it in the License.swift file to enable the display of a photo’s license details:
Step 3: Update the ViewModel to use the Codable data models
Given the JSON results and the Codable models, I represent the photostream as a Swift array of Photos in the ViewModel: [Photo]. (More details on the ViewModel will be the focus of my next article.)
OAuth 1.0 Authentication
While some API calls are available to any registered API user, other API calls are only available based on authenticated users. Flickr is no different in its API implementation. The endpoints related to the “favorites” (lines 5–7 above) are examples of API methods that require authentication and only return valid data for an authenticated user.
OAuth (Open Authentication) is a protocol many services like Flickr use for access delegation. OAuth has been around since 2006 and has gone through several changes. The latest version is OAuth2.0, but Flickr still uses OAuth1.0. That said, instead of using an “off the shelf” iOS library for OAuth, I had to develop a custom OAuth1.0 implementation in Swift.
Flickr provides an overview of the OAuth1.0 access delegation process:
Let’s walkthrough the steps above using my OAuth1.0 implementation. First, we have Step 1 (Request Token):
Now Steps 1 through 3 together:
The reader can find the complete FlickrOAuthService.swift file in the GitHub repository at the end of the article.
I also developed an authentication state model to use with the ViewModel:
What’s Next?
In my next article, I will explore my use of Apple’s Combine framework in the ViewModel to exchange data with Flickr using the API, JSON, and OAuth code from this article.
Until next time, stay safe and keep learning!
The full repository is available at the link below and will allow the reader to explore further the details of each screen and view included in the app:
