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.
The latest version of KituraKit requires Swift 4.0 or later. You can download this version of the Swift binaries by following this link.
-
Navigate to the root of your project (where your .xcodeproj directory is)
-
If you don't already have a podfile, run
pod initto 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 installalso creates an Xcode workspace which contains all of your installed pods. So you'll need to open the.xcworkspacefile (not.xcodeproj) to have access to those pods. This is the default behaviour of Cocoapods.
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 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 KituraKitTo 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.
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
}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
}
}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.
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.
We love to talk server-side Swift and Kitura. Join our Slack to meet the team!
This library is licensed under Apache 2.0. Full license text is available in LICENSE.