Spine

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.

Stability

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!

Supported features

Feature	Supported	Note
Fetching resources	Yes
Creating resources	Yes
Updating resources	Yes
Deleting resources	Yes
Top level metadata	Yes
Top level errors	Yes
Top level links	Partially	Only pagination links are supported
Top level JSON API Object	Yes
Client generated ID's	No
Resource metadata	Yes
Custom resource links	No
Relationships	Yes
Inclusion of related resources	Yes
Sparse fieldsets	Partially	Fetching only, all fields will be saved
Sorting	Yes
Filtering	Yes	Supports custom filter strategies
Pagination	Yes	Offset, cursor and custom pagination strategies
Bulk extension	No
JSON Patch extension	No

Installation

Carthage

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

Cocoapods

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

Quickstart

1. Instantiate a Spine

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

2. Register your resource classes

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 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(),
			"author": ToOneRelationship(User),
			"comments": ToManyRelationship(Comment)
		])
	}
}


// Register resource class
spine.registerResource(Post)

3. Fetching resources

Using find methods

// 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.findAll(Post.self) // Fetch all posts
spine.findOne("1", ofType: Post.self)  // Fetch a single posts with ID 1

Using a Query

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("creationDate") // 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.

4. Saving resources

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.

5. Deleting resources

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

Deleting does not cascade on the client.

6. Read the wiki

The wiki contains much more information about using Spine.

Memory management

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:

Declare one end of the relationship as weak or unowned.
Use a Resource's unload method to break cycles when you are done with the resource.

krasnoukhov/Spine