Example iOS Project 💡

This chapter provides a sample Xcode project to see the basic usage of the Yoli API in action.

⬇️ You can download the Xcode project here

Basic Information

  • Native iOS Xcode project
  • Swift 4.1 as programming language
  • iOS 11.4 as Base SDK
  • iOS 10.0 as Deployment Target
  • Alamofire for Networking

The Example App

The app in the example project has a very basic user interface and includes some example queries and mutations against the Yoli API. It should showcase the usage of the Yoli API and is not engineered to be bullet proof.

Welcome Screen

The first screen allows the user to enter his/her name and press then the continue button. This will create a user on the Yoli API and sets the entered name as username.

iOS Example Project Screen 1

Bank Login Screen

On the second screen the user has the possibility to connect a bank account. The sample project simply connects a demo bank account. You can look into the code to see how this works.

iOS Example Project Screen 2

After the user taps on Connect Now the view changes into a loading mode where an activity indicator and a description label appears. The Yoli API now connects the bank account, loads the transactions and starts the contract detection. iOS Example Project Screen 3

Contracts Screen

On the final screen the user can see the detected contracts together with the determined category, amount and interval.

iOS Example Project Screen 4

Project Structure

We have structured the example project so that you can find your way in as easily as possible. Everything code related is contained in the group named Code. There you see groups for the three mentioned ViewControllers in ViewControllers. Also both Storyboards are grouped in Storyboards. Model contains all model structs. All of these conform to Codable.

iOS Example Project Structure

Model Group

Additionally Model contains two additional groups: TokenHandling and Pages. TokenHandling just contains the struct which holds all needed tokens. The more interesting part is Pages: It's the nature of GraphQL responses, that the data you need is not directly available at root. E.g. when you look at this response when requesting me: User:

  "data": {
    "me": {
      "username": "John",
      "contracts": []

To not write model code in boilerplate style to be able to map every possible response, we use two generic classes. On first level there is GraphQLPage which maps the root object, which itself contains the data field. This struct is documented in Using GraphQL in iOS. On second level, there is always the (at least one) result of what you have requested. To map this you normally have to write a something like this:

struct MePage: Codable {
  let me: User

To make this generic we use ValuePage. It accepts every Codable struct or class and maps it for you. Important: When you want to use ValuePage you have to rename your query to value. You can do this directly in your GraphQL script, just check them out.

Additionally there exists a SuccessPage which makes the same for success style results. E.g. used in the changeName mutation. We could use the ValuePage for this as well, but we thought it is better understandable on ViewController side when we use success as property name, not value. Especially when mutating Bools it is important to distinguish whether the result is the new value or a success state.

Networking Group

The Networking group contains a custom JSON decoder class since there exist three date formats in Yoli. This is because we connect in Yoli several services which all have their own date format. We try to unify this in the future. Also there is the Client.swift which contains some example interfaces to the Yoli API and the implementation of request and authorizedRequest. More about Client.swift at Networking.

Networking contains another group called GraphQL. This contains itself GraphQL.swift. More about GraphQL.swift at Using GraphQL in iOS. Additionally the GraphQL group contains all queries and mutations.

What's Next?

On the next page we describe all the requests from the example project in detail.