Skip to content

Making Requests

Jump to bottom
Andrew Wagner edited this page Sep 10, 2019 · 5 revisions

Overview

Types of Methods

Every endpoint type has two or three ways to make a request: asynchronously, synchronously, and as a download, but they look different depending on the type.

Asynchronous

Most of the time, you will want to use the asynchronous methods. In an app environment, this allows your app to remain responsive while the request is being made.

Synchronous

These methods should only be used when you're ok with the current thread being blocked until the entirety of the request is complete. They were designed to be used from a background thread, especially in a backend environment.

Download

This is useful for large, usually raw data requests like downloading a file. It's advisable to use this if you expect a large amount of data so that all of that data doesn't have to be held in memory. Instead, the data is streamed to the file system. Because of this, download requests are only available on endpoints with output.

EmptyEndpoint

Asynchronously

CheckStatus().makeRequest() { result in
    switch result {
    case .success:
        print("Success :)")
    case .failure(let error):
        print("Error :( \(error)")
    }
}

The callback will be called no matter what and you can handle the success or failure cases in the switch statement.

Synchronously

try CheckStatus().makeSynchronousRequest()

This will throw an error if there are any problems making the request.

InEndpoint

An endpoint that takes input does so in the makeRequest method.

CreateObject().makeRequest(with: .init(name: "Jane")) { result in
    switch result {
    case .success:
        print("Success :)")
    case .failure(let error):
        print("Error :( \(error)")
    }
}

It is very similar for the synchronous request.

try CreateObject().makeSynchronousRequest(with: .init(name: "Jane"))

OutEndpoint

The callback of makeRequest on an OutEndpoint returns a Result<Output, Error> so that you can access the output from the result.

GetDefaultObject().makeRequest() { result in
    switch result {
    case .success(let output):
        print("Name: \(output.name)")
    case .failure(let error):
        print("Error :( \(error)")
    }
}

Since these endpoints have output, there is also a download method.

GetDefaultObject().makeDownloadRequest() { result in
    switch result {
    case .success(let url):
        // Open or move the url. Otherwise, it will be deleted when
        // callback returns.
        print("Name: \(url)")
    case .failure(let error):
        print("Error :( \(error)")
    }
}

The asynchronous request returns the Output type.

try GetDefaultObject().makeSynchronousRequest()

InOutEndpoint

The InOutEndpoint is a combination of the InEndpoint and OutEndpoint formats.

Login().makeRequest(with: .init(username: "username", password: "secret")) { result in
    switch result {
    case .success(let output):
        print("Token: \(output.token)")
    case .failure(let error):
        print("Error :( \(error)")
    }
}

Since these endpoints have output, there is also a download method.

Login().makeDownloadRequest((with: .init(username: "username", password: "secret")) { result in
    switch result {
    case .success(let url):
        // Open or move the url. Otherwise, it will be deleted when
        // callback returns.
        print("Name: \(url)")
    case .failure(let error):
        print("Error :( \(error)")
    }
}

So the synchronous method takes the input and returns the output.

let token = try Login().makeSynchronousRequest(with: .init(username: "username", password: "secret")).token

Extra Options

Examples of the most basic uses of each request method are above, but there are also a few other extra optional arguments available on asynchronous and download requests.

Callback Queue

By default, all callbacks will be called on the main thread, but this allows you to override that behavior. You can set it to nil if it doesn't matter what thread it is called on.

Progress Callback

Only available on iOS 11+, macOS10.13+, and tvOS11+

With this parameter, you can provide a callback that will be called periodically updating you on the progress of the requests. It's designed to allow reporting progress to your user.

Clone this wiki locally