iOS Apps with REST APIs(一)

Important note: This is a series of tutorials, not original by me, but a tutorial translated from abroad. I am also learning Swift, and seeing this tutorial is very helpful for developing an actual APP, so the translation is shared with everyone. The original tutorial is very long, I will translate and publish it one after another, welcome to communicate and share.
In addition, the original tutorial has the first chapter, which describes the tutorial and related basic concepts. I feel that there is no need to translate it, so I skip it here. If you are interested, you can find the original tutorial online.

Again, the original text is published in my blog: iOS Apps with REST APIs (1)

App requirements

It's always tempting for us coders to go straight to coding, but if we figure out what we're going to do in advance and plan ahead, can we make coding smoother? Or at least we need to have some idea of ​​the application (App) we need to write. Ok, let's list the requirements of the gist s application (App), you can modify it according to the application you want to build.

First, let's list those interfaces in the application. Of course there are many ways we can do this, but I like to list what the user wants to accomplish with the app first, and then it's a lot easier to design the interface.

So what will our users do with gists ? Gists are snippets of code that can be shared with other users via GitHub. So the user may need the following functionality via gists :

1. Check out the list of public gists repositories to see what's new;
2. Query the gists library of interest, usually through a programming language;
3. Favorite/follow a gists library, you can view it later;
4. View the list of gists libraries that you have collected/followed;
5. Check your own gists library and save some commonly used codes, so you don't have to type it again every time in the future;
6. View details of public, own or favorite gists repositories;
7. create new gists library;
8. Remove your own gists library.

List tasks or user stories in your app. Make a comparison with the gists App, and focus on different objects (such as collections, users, and gists libraries) and actions (such as viewing lists, viewing details of an object, adding, deleting, etc.).

Maybe your list is very long, then you need to consider whether all of them need to be implemented in the first version, and if not, which features can be separated to be implemented in the next version.

Now evaluate each feature on your list and decide which ones need to be implemented in the first release. By now you might be thinking about designing a second edition. However, a working app is far better than a perfect app that is delayed indefinitely.

Match functions with API endpoints

Next, for each item in the feature list, we figure out how to use the API interface to get the data that needs to be displayed. We check the Github GISTs API documentation and find the corresponding API endpoint for each feature. We also flag which API endpoints require special handling, such as authentication or pagination.

List of public gists libraries

  GET /gists/public

Authentication is not required. If we look at 20 or more, then we need to use pagination to load more data.

Query the Gists library

Github does not provide an interface for this. If our application does not have the query function, it is still very good, so we will not do this function first.

Favorite/Unfavorite Gists Library

  PUT /gists/:id/star
  DELETE /gists/:id/star

Authentication is required.

Favorites list

  GET /gists/starred

Authentication is required.

My Gists List

There are two ways to get a list of gists for a user:

  GET /users/:username/gists

If verified, you can use:

  GET /gists

View Gist Details

We can pass the details data of gists to the details page through the list view. If not, we can get it through the following:

  GET /gists/:id

If we want to determine whether a gists is favorited, we can use:

  GET /gists/:id/star

Create Gists

  POST /gists

If you want to create a user's own Gists library, you need to authenticate first, otherwise the creator of the created library will be anonymous.
The JSON data structure submitted at creation time is as follows:

{
  "description": "gist库的描述",
  "public": true,
  "files": {
    "file1.text": {
      "content": "文件内容，或者代码"
    }
  }
}

Remove Gists

  DELETE /gists/:id

Authentication is required.

These are all the endpoints we need. Even though no query-related APIs are provided, it is sufficient to use these APIs to write this sample application.

Analyzing each feature and listing the corresponding API endpoints or iOS features is a must. We want to make sure that these APIs are valid, if not and they are maintained by your own team, then apply quickly to allow ample time to implement these APIs.

User Interface

Next, let's design our application so that users can use it. We will analyze each task and show how to use it accordingly. Below is my reordering of functions by interface usage.

Certification process

When the function operated by the user requires authentication before it can be used, then we will first perform the user authentication check. If it does not pass, then start the login process to allow the user to log in.

If your app has many features that allow users to use them without logging in, then perhaps you want to delay logging in users. Therefore, for interfaces that need to be called after login, you must check whether the user is logged in before calling.

List of public Gists

The homepage is a list of public Gists (using table view table view).

my collection

From the public list, the user can switch to the list of my favorites.

my Gists

Users from public lists or my favorites can switch to my Gists.
The above three lists are very similar, can we use a table view with a selector, the user can switch between these three views by selecting.

View Gists Details

When the user clicks on one of the Gists in the list, we transition to a different view. In this view, the Gists information (description and file name) will be listed in detail and the content of the file can be viewed by the user. At the same time, the interface will also show whether we have collected the Gists.

Favorite/Unfavorite Gists

In the details page, we will display the status of the favorite, and can click to favorite or unfavorite.

New Gists

There is a button in the top right corner of my Gists list view. +Clicking this button will display an entry form, which the user can use to create a new Gists. The information that needs to be entered in the form is:

• description: a piece of text;
• Is it public: boolean;
• filename:text;
• File content: text.
  To keep things simple, in version 1.0 only one file is allowed to be created in Gists.

Remove Gists

A Gists can be removed by swiping in the My Gists view.

Check your function list and give the user interface so that the user can complete these functions.

API requirements

When we comb through these user functions, we will find that some of the required APIs are not so obvious. Therefore, we need to read carefully in order to put together a list of lists.

Certification

When unauthenticated, we can read public Gists and can create a Gists anonymously. However, when private Gists need to be read or edited, OAuth authentication is required. See the Github Gists API documentation .

Therefore, we need to authenticate the user. For integration, OAuth2.0 is preferred. The interface uses username/password for authentication, but we don't need to worry about these sensitive data. Because, OAuth2.0 will not let us see the username and password, but the interaction is only the user's application token ( token). We will safely store the OAuth token.

Check your API authentication requirements. In the authentication chapters that follow, we will implement OAuth2.0 authentication, token-based authentication, and the most basic username/password authentication.

Set the Accept header (Accept Header)

As described in the Github API documentation, we have to set the request Acceptheaders like this:

  Accept: application/vnd.github.v3+json

That is, if you don't set it, the returned result will not be what you expect. Therefore, we will deal with it in subsequent development.

Check your API documentation to see what else needs to be set.

In iOS9, Apple introduced the concept of App Transport Security (ATS) , see here for details . ATS requires SSL for data transfer, which is very finicky to implement. Sadly, many servers today do not meet this requirement. However, GitHub's gist API is ATS-compliant, so we don't have to add extra processing.

If you get an SSL error when calling your own API in iOS9, you need to add ATS error handling. You can see the details of how to solve it in the next chapter. You can use the code in this chapter to try to call some simple API provided by your server to see if there are any SSL errors.

Make a development plan

Now we know what we're going to do, and how to do it. Then we will gradually implement these functions to improve the APP.

• Create our app and add a table view to display the list of public Gists;
• Add custom header (header);
• Load the image in the table view;
• Load more Gists when the user scrolls to the bottom;
• Add pull-down refresh function;
• Added authentication so that users can switch to my Gists and My Favorites list;
• Create a Gists' detail page;
• Add favorite/unfavorite function on the details page;
• Add delete and new functions;
• Increase the processing when there is no network.

List your views and functions in order of implementation. Try to match the development order of the Gists App. If your API requires authentication to be able to call, then you need to skip to the authentication chapter first, and then come back. If you need to add custom headers to all your requests, you need to skip to the headers section first.

We have now laid out the basic requirements of the application and know how to get started. But, before we get started, let's take a moment to understand how web requests are made in Swift , and JSON parsing, so that we don't get bogged down in the details later.

 

You can follow my WeChat public account (CD826Workshop) to communicate.

​