Spine is a Swift library for working with APIs that adhere to the jsonapi.org standard. It supports mapping to custom model classes, fetching, advanced querying, linking and persisting.

This library was born out of a hobby project. Some things are still lacking, one of which is test coverage. Beware of this when using Spine in a production app!

Add github "wvteijlingen/Spine" "swift-2.0" to your Cartfile. See the Carthage documentation for instructions on how to integrate with your project using Xcode.

Add pod 'Spine', :git => 'https://github.com/wvteijlingen/Spine.git', :branch => 'swift-2.0' to your Podfile. The spec is not yet registered with the Cocoapods repository, because the library is still in flux.

let baseURL = NSURL(string: "http://api.example.com/v1")
let spine = Spine(baseURL: baseURL)

Every resource is mapped to a class that inherits from Resource. A subclass should override the variables resourceType and fields. The resourceType should contain the type of resource in plural form. The fields array should contain an array of fields that must be persisted. Fields that are not in this array are ignored.

Each class must be registered using a factory method. This is done using the registerResource method.

// Resource class
class Post: Resource {
	dynamic var title: String?
	dynamic var body: String?
	dynamic var creationDate: NSDate?
	dynamic var author: User?
	dynamic var comments: LinkedResourceCollection?

	override class var resourceType: String {
		return "posts"
	}

	override class var fields: [Field] {
		return fieldsFromDictionary([
			"title": Attribute(),
			"body": Attribute().serializeAs("content"),
			"creationDate": DateAttribute().serializeAs("created-at"),
			"author": ToOneRelationship(User.resourceType),
			"comments": ToManyRelationship(Comment.resourceType)
		])
	}
}


// Register resource class
spine.registerResource(Post.resourceType) { Post() }

// Fetch posts with ID 1 and 2
spine.find(["1", "2"], ofType: Post.self).onSuccess { resources, meta, jsonapi in
    println("Fetched resource collection: \(resources)")
.onFailure { error in
    println("Fetching failed: \(error)")
}

spine.findOne("1", ofType: Post.self)  // Fetch a single posts with ID 1
spine.find(Post.self) // Fetch all posts
spine.findOne(Post.self) // Fetch the first posts

var query = Query(resourceType: Post.self)
query.include("author", "comments", "comments.author") // Sideload relationships
query.whereProperty("upvotes", equalTo: 8) // Only with 8 upvotes
query.addAscendingOrder("created-at") // Sort on creation date

spine.find(query).onSuccess { resources, meta, jsonapi in
    println("Fetched resource collection: \(resources)")
.onFailure { error in
    println("Fetching failed: \(error)")
}

All fetch methods return a Future with onSuccess and onFailure callbacks.

spine.save(post).onSuccess { _ in
    println("Saving success")
.onFailure { error in
    println("Saving failed: \(error)")
}

Extra care MUST be taken regarding related resources. Saving does not automatically save any related resources. You must explicitly save these yourself beforehand. If you added a new create resource to a parent resource, you must first save the child resource (to obtain an ID), before saving the parent resource.

spine.delete(post).onSuccess {
    println("Deleting success")
.onFailure { error in
    println("Deleting failed: \(error)")
}

Deleting does not cascade on the client.

The wiki contains much more information about using Spine.

Spine suffers from the same memory management issues as Core Data, namely retain cycles for recursive relationships. These cycles can be broken in two ways:

1. Declare one end of the relationship as weak or unowned.
2. Use the unloadResource function to unload resources and break cycles when you are done with a resource.

The tests can be run by selecting the test called SpineTests in the Xcode scheme selector, and then choosing 'Product > Test' or ⌘U.