Obsidian iOS SDK

Welcome

The Obsidian iOS SDK provides a Swift interface to the Obsidian Server API. Follow the instructions below to get up-and-running quickly.

Configuring Environments

The Obsidian iOS SDK allows for easy environment management. The Environment enum contains three states: Development, Staging, and Production. For demonstration purposes, we’ll configure the Development state to connect to a server running locally:

let baseURL = NSURL(string: "http://127.0.0.1:8000")!

Environment.Development.configure(
    key: "<your client key>", 
    secret: "<your client secret>", 
    base: baseURL
)

Next, we’ll activate the Development environment:

Environment.Development.setCurrent()

This initial configuration is typically perfomed in the application:didFinishLaunchingWithOptions: method of your application’s delegate.

For more information, consult the Environment section of the documentation.

Creating a Resource

All of your application’s resources should inherit from the Resource class. By doing so, your resources can take advantage of the SDK’s value mapping system, as well as some useful convenience methods.

For this demonstration, we’ll assume we have a resource called employee defined in our server’s resources.json file. Let’s also assume that the employee resource has an attribute called address of type string specified in its definition.

When subclassing Resource, we must override var name: String as well as required init(mapper: Mapper).

import Foundation
import Obsidian_iOS_SDK

class Employee: Resource {

    // This class variable provides the SDK with the class's corresponding server-side resource name
    override class var name: String {
        return "employee"
    }

    // This property's setter is private so that it can be manipulated by the Mapper
    private(set) var address: String!

    // This initializer is called every time an Employee needs to be deserialized
    required init(mapper: Mapper) {

        /* 
        ** The <- operator defines a mapping between an attribute's server side
        ** representation (mapper["address"]) and its local property (self.address).
        */

        address <- mapper["address"]        

        super.init(mapper: mapper)
    }
}

For more information, consult the Resource and Mapper sections in the documentation.

Making Requests

To look up some employees, we’ll use the read class method provided by the Resource class:

Employee.read { (response: Response<Employee>) -> Void in

    // Since Response is an enum, we can switch over the possible outcomes
    switch(response) {

    // If the operation succeeded, print the address of the first result
    case .Success(let results):    
        println(results.firstResult?.address)
        break        

    /*
    ** If the operation failed, log it to the console.
    ** NOTE: There are more descriptive error states defined in the Response Enum Reference.
    */
    default:
        print("oh no! an error occurred!")
        break   
    }
}

The built-in create, update, and delete requests work similarly. Consult the documentation for more information.

Documentation

See the documentation at CocoaDocs.

Getting Help

Please direct all bugs, feature requests, and other concerns to Nick Lee, [email protected]

License

The Obsidian iOS SDK is released under the MIT license. See LICENSE for details.