KituraKit - A Kitura v2 Client Library

Kitura is a lightweight web framework for writing Swift server applications.

KituraKit is a client side framework for sending HTTP requests to a Kitura server. By using the Swift Codable protocol, you can send and receive models directly from client to server.

Swift version

The latest version of KituraKit requires Swift 4.0 or later. You can download this version of the Swift binaries by following this link.

Usage

Cocoapod Installation

Navigate to the root of your project (where your .xcodeproj directory is)
If you don't already have a podfile, run pod init to create a new podfile in your current directory.
Open the Podfile with your preferred text editor and under the "# Pods for 'your_project_name'>" line add:

pod 'KituraKit'

Install KituraKit by running the command: pod install
As well as installing KituraKit, the pod install also creates an Xcode workspace which contains all of your installed pods. So you'll need to open the .xcworkspace file (not .xcodeproj) to have access to those pods. This is the default behaviour of Cocoapods.

SPM Installation

We expect users on the client side to use the Cocoapod installation, however, if you require access to KituraKit from the server you can use Swift Package Manager.

Add dependencies

Add the KituraKit package to the dependencies within your application’s Package.swift file. Substitute "x.x.x" with the latest KituraKit release.

.package(url: "https://github.com/IBM-Swift/KituraKit.git", from: "x.x.x")

Add KituraKit to your target's dependencies:

.target(name: "example", dependencies: ["KituraKit"]),

Import package

import KituraKit

Examples

To run through a FoodTracker tutorial which covers various components of Kitura, including KituraKit, click here

To try out the sample iOS project for yourself, making use of KituraKit, click here.

API Documentation

KituraKit

The KituraKit class handles the connection to your Kitura server and executes the REST requests.

You create a KituraKit instance by providing the URL of your Kitura server:

if let client = KituraKit(baseURL: "http://localhost:8080") {
    // Use client to make requests here
}

Codable Models

Kitura and KituraKit send and receive instances of Swift types directly. These types (aka models) can be shared between the client and server.

The only requirement for a model is that it conforms to the Codable protocol:

public struct User: Codable {
    public let name: String
    public init(name: String) {
        self.name = name
    }
}

HTTP Requests

The signatures for HTTP requests in KituraKit mirror the Codable routes in Kitura. We will demonstrate what the code for this looks like in the following examples.

If you had the following GET route on your server:

// Kitura server route
router.get("/users") { (completion: ([User]?, RequestError?) -> Void) in
    let users = [User(name: "Joe"), User(name: "Bloggs")]
    completion(users, nil)
}

You would make a request to it using the get function on your KituraKit client:

// KituraKit client request
client.get("/users") { (users: [User]?, error: RequestError?) -> Void in
    if let users = users {
        // GET successful, work with returned users here
    }
}

Similarly, to make a request to a Kitura POST route:

// Kitura server route
router.post("/users") { (user: User, completion: (User?, RequestError?) -> Void) in
    completion(user, nil)
}

You would make a request to it using the post function on your KituraKit client:

// KituraKit client request
let newUser = User(name: "Kitura")
client.post("/users", data: newUser) { (user: User?, error: RequestError?) -> Void in
    if let user = user {
        // POST successful, work with returned users here
    }
}

KituraKit supports the following REST requests:

GET a Codable object.
GET a Codable object using an identifier.
GET a Codable object using query parameters.
POST a Codable object.
POST a Codable object and be returned an identifier.
PUT a Codable object using an identifier.
PATCH a Codable object using an identifier.
DELETE using an identifier.
DELETE without an identifier.

Authentication

The Kitura server can authenticate users using the Credentials repository. KituraKit allows you to provide credentials alongside your request to identify yourself to the server.

Note: When sending credentials you should always use HTTPS to avoid sending passwords/tokens as plaintext.

You can set default credentials for your client which will be attached to all requests. If your server is using Kitura-CredentialsHTTP for basic authentication, you would provide the username and password as follows:

if let client = KituraKit(baseURL: "https://localhost:8080") {
    client.defaultCredentials = HTTPBasic(username: "John", password: "12345")
}

Alternatively, you can provide the credentials directly on the request:

let credentials = HTTPBasic(username: "Mary", password: "abcde")
client.get("/protected", credentials: credentials) { (users: [User]?, error: RequestError?) -> Void in
    if let users = users {
        // work with users
    }
}

KituraKit supports client side authentication for the following plugins:

HTTP Basic using Kitura-CredentialsHTTP.
Facebook OAuth token using Kitura-CredentialsFacebook
Google OAuth token using Kitura-CredentialsGoogle
JWT token (Kitura-CredentialsJWT coming soon)

For more information visit our API reference.

Community

We love to talk server-side Swift and Kitura. Join our Slack to meet the team!

License

This library is licensed under Apache 2.0. Full license text is available in LICENSE.

hactar / KituraKit