Vox

Vox is a Swift JSONAPI standard implementation. 🔌

🔜 More stable version (written in Swift 5) coming soon.

🎩 The magic behind
💻 Installation
🚀 Usage
✅ Tests
Contributing
License

The magic behind

Vox combines Swift with Objective-C dynamism and C selectors. During serialization and deserialization JSON is not mapped to resource object(s). Instead, it uses Marshalling and Unmarshalling techniques to deal with direct memory access and performance challenges. Proxy (surrogate) design pattern gives us an opportunity to manipulate JSON's value directly through class properties and vice versa.

import Vox

class Person: Resource {
    @objc dynamic var name: String?
}

let person = Person()
    person.name = "Sherlock Holmes"
    
    print(person.attributes?["name"]) // -> "Sherlock Holmes"

Let's explain what's going on under the hood!

Setting the person's name won't assign the value to Person object. Instead it will directly mutate the JSON behind (the one received from server).
Getting the property will actually resolve the value in JSON (it points to its actual memory address).
When values in resource's attributes or relationship dictionaries are directly changed, getting the property value will resolve to the one changed in JSON.

Every attribute or relationship (Resource subclass property) must have @objc dynamic prefix to be able to do so.

Think about your Resource classes as strong typed interfaces to a JSON object.

This opens up the possibility to easily handle the cases with:

I/O performance
polymorphic relationships
relationships with circular references
lazy loading resources from includes list

Installation

Requirements

Xcode 9
Cocoapods

Basic

pod 'Vox'

With Alamofire plugin

pod 'Vox/Alamofire'

Usage

Defining resource

import Vox

class Article: Resource {

    /*--------------- Attributes ---------------*/
    
    @objc dynamic
    var title: String?
    
    @objc dynamic
    var descriptionText: String?

    @objc dynamic
    var keywords: [String]?
    
    @objc dynamic
    var viewsCount: NSNumber?
    
    @objc dynamic
    var isFeatured: NSNumber?
    
    @objc dynamic
    var customObject: [String: Any]?
    
    /*------------- Relationships -------------*/
        
    @objc dynamic
    var authors: [Person]?

    @objc dynamic
    var editor: Person?

    /*------------- Resource type -------------*/

    // resource type must be defined
    override class var resourceType: String {
        return "articles"
    }

    /*------------- Custom coding -------------*/

    override class var codingKeys: [String : String] {
        return [
            "descriptionText": "description"
        ]
    }
}

Serializing

Single resource

import Vox
            
let person = Person()
    person.name = "John Doe"
    person.age = .null
    person.gender = "male"
    person.favoriteArticle = .null()
            
let json: [String: Any] = try! person.documentDictionary()

// or if `Data` is needed
let data: Data = try! person.documentData()

Previous example will resolve to following JSON:

{
  "data": {
    "attributes": {
      "name": "John Doe",
      "age": null,
      "gender": "male"
    },
    "type": "persons",
    "id": "id-1",
    "relationships": {
      "favoriteArticle": {
        "data": null
      }
    }
  }
}

In this example favorite article is unassigned from person. To do so, use .null() on resource properties and .null on all other properties.

Resource collection

import Vox

let article = Article()
    article.id = "article-identifier"

let person1 = Person()
    person1.id = "id-1"
    person1.name = "John Doe"
    person1.age = .null
    person1.gender = "male"
    person1.favoriteArticle = article

let person2 = Person()
    person2.id = "id-2"
    person2.name = "Mr. Nobody"
    person2.age = 99
    person2.gender = .null
    person2.favoriteArticle = .null()


let json: [String: Any] = try! [person1, person2].documentDictionary()

// or if `Data` is needed
let data: Data = try! [person1, person2].documentData()

Previous example will resolve to following JSON:

{
  "data": [
    {
      "attributes": {
        "name": "John Doe",
        "age": null,
        "gender": "male"
      },
      "type": "persons",
      "id": "id-1",
      "relationships": {
        "favoriteArticle": {
          "data": {
            "id": "article-identifier",
            "type": "articles"
          }
        }
      }
    },
    {
      "attributes": {
        "name": "Mr. Nobody",
        "age": 99,
        "gender": null
      },
      "type": "persons",
      "id": "id-2",
      "relationships": {
        "favoriteArticle": {
          "data": null
        }
      }
    }
  ]
}

Nullability

Use .null() on Resource type properties or .null on any other type properties.

Setting property value to .null (or .null()) will result in JSON value being set to null
Setting property value to nil will remove value from JSON

Deserializing

Single resource

import Vox

let data: Data // -> provide data received from JSONAPI server

let deserializer = Deserializer.Single<Article>()

do {
    let document = try deserializer.deserialize(data: self.data)
    
    // `document.data` is an Article object
    
} catch JSONAPIError.API(let errors) {
    // API response is valid JSONAPI error document
    errors.forEach { error in
        print(error.title, error.detail)
    }
} catch JSONAPIError.serialization {
    print("Given data is not valid JSONAPI document")
} catch {
    print("Something went wrong. Maybe `data` does not contain valid JSON?")
}

Resource collection

import Vox

let data: Data // -> provide data received from JSONAPI server

let deserializer = Deserializer.Collection<Article>()

let document = try! deserializer.deserialize(data: self.data)

// `document.data` is an [Article] object

Description

Provided data must be Data object containing valid JSONAPI document or error. If this preconditions are not met, JSONAPIError.serialization error will be thrown.

Deserializer can also be declared without generic parameter but in that case the resource's data property may need an enforced casting on your side so using generics is recommended.

Document<DataType: Any> has following properties:

Property	Type	Description
`data`	`DataType`	Contains the single resource or resource collection
`meta`	`[String: Any]`	`meta` dictionary
`jsonapi`	`[String: Any]`	`jsonApi` dictionary
`links`	`Links`	`Links` object, e.g. can contain pagination data
`included`	`[[String: Any]]`	`included` array of dictionaries

Networking

<id> and <type> annotations can be used in path strings. If possible, they'll get replaced with adequate values.

Client protocol

Implement following method from Client protocol:

func executeRequest(path: String,
                  method: String,
              queryItems: [URLQueryItem],
          bodyParameters: [String : Any]?,
                 success: @escaping ClientSuccessBlock,
                 failure: @escaping ClientFailureBlock,
                userInfo: [String: Any])

where

ClientSuccessBlock = (HTTPURLResponse?, Data?) -> Void
ClientFailureBlock = (Error?, Data?) -> Void

Note:

userInfo contains custom data you can pass to the client to do some custom logic: e.g. add some extra headers, add encryption etc.

Alamofire client plugin

If custom networking is not required, there is a plugin which wraps Alamofire and provides networking client in accordance with JSON:API specification.

Alamofire is Elegant HTTP Networking in Swift

Example:

let baseURL = URL(string: "http://demo7377577.mockable.io")!
let client = JSONAPIClient.Alamofire(baseURL: baseURL)
let dataSource = DataSource<Article>(strategy: .path("vox/articles"), client: client)

dataSource
    .fetch()
    ...

Installation

pod 'Vox/Alamofire'

Fetching single resource

let dataSource = DataSource<Person>(strategy: .path("custom-path/<type>/<id>"), client: client)

dataSource
    .fetch(id:"1")
    .include([
        "favoriteArticle"
    ])
    .result({ (document: Document<Person>) in
        let person = document?.data // ➜ `person` is `Person?` type
    }) { (error) in
        if let error = error as? JSONAPIError {
            switch error {
            case .API(let errors):
                ()
            default:
                ()
            }
        }
    }

Fetching resource collection

let dataSource = DataSource<Person>(strategy: .path("custom-path/<type>"), client: client)

dataSource(url: url)
    .fetch()
    .include([
        "favoriteArticle"
    ])
    .result({ (document: Document<[Person]>) in
        let persons = document.data // ➜ `persons` is `[Person]?` type
    }) { (error) in
        
    }

Creating resource

let person = Person()
    person.id = "1"
    person.name = "Name"
    person.age = 40
    person.gender = "female"
            
let dataSource = DataSource<Person>(strategy: .path("custom-path/<type>"), client: client)

dataSource
    .create(person)
    .result({ (document: Document<Person>?) in
        let person = document?.data // ➜ `person` is `Person?` type
    }) { (error) in
        
    }

Updating resource

let person = Person()
    person.id = "1"
    person.age = 41
    person.gender = .null
            
let dataSource = DataSource<Person>(strategy: .path("custom-path/<type>/<id>"), client: client)

dataSource
    .update(resource: person)
    .result({ (document: Document<Person>?) in
        let person = document?.data // ➜ `person` is `Person?` type
    }) { (error) in
        
    }

Deleting resource

let dataSource = DataSource<Person>(strategy: .path("custom-path/<type>/<id>"), client: client)
            
dataSource
    .delete(id: "1")
    .result({
            
    }) { (error) in
        
    }

Pagination

Pagination on initial request

Custom pagination strategy

let paginationStrategy: PaginationStrategy // -> your object conforming `PaginationStrategy` protocol

let dataSource = DataSource<Person>(strategy: .path("custom-path/<type>"), client: client)

dataSource
    .fetch()
    .paginate(paginationStrategy)
    .result({ (document) in
        
    }, { (error) in
        
    })

Page-based pagination strategy

let paginationStrategy = Pagination.PageBased(number: 1, size: 10)

let dataSource = DataSource<Person>(strategy: .path("custom-path/<type>"), client: client)

dataSource
    .fetch()
    .paginate(paginationStrategy)
    .result({ (document) in
        
    }, { (error) in
        
    })

Offset-based pagination strategy

let paginationStrategy = Pagination.OffsetBased(offset: 10, limit: 10)

let dataSource = DataSource<Person>(strategy: .path("custom-path/<type>"), client: client)

dataSource
    .fetch()
    .paginate(paginationStrategy)
    .result({ (document) in
        
    }, { (error) in
        
    })

Cursor-based pagination strategy

let paginationStrategy = Pagination.CursorBased(cursor: "cursor")

let dataSource = DataSource<Person>(strategy: .path("custom-path/<type>"), client: client)

dataSource
    .fetch()
    .paginate(paginationStrategy)
    .result({ (document) in
        
    }, { (error) in
        
    })

Appending next page to current document

document.appendNext({ (data) in
    // data.old -> Resource values before pagination
    // data.new -> Resource values from pagination
    // data.all -> Resource values after pagination
    
    // document.data === data.all -> true
}, { (error) in

})

Fetching next document page

document.next?.result({ (nextDocument) in
    // `nextDocument` is same type as `document`
}, { (error) in
    
})

Fetching previous document page

document.previous?.result({ (previousDocument) in
    // `previousDocument` is same type as `document`
}, { (error) in
    
})

Fetching first document page

document.first?.result({ (firstDocument) in
    // `firstDocument` is same type as `document`
}, { (error) in
    
})

Fetching last document page

document.last?.result({ (lastDocument) in
    // `lastDocument` is same type as `document`
}, { (error) in
    
})

Reloading current document page

document.reload?.result({ (reloadedDocument) in
    // `reloadedDocument` is same type as `document`
}, { (error) in
    
})

Custom routing

Generating URL for resources can be automated.

Make a new object conforming Router. Simple example:

class ResourceRouter: Router {
    func fetch(id: String, type: Resource.Type) -> String {
        let type = type.resourceType
        
        return type + "/" + id // or "<type>/<id>"
    }
    
    func fetch(type: Resource.Type) -> String {
        return type.resourceType // or "<type>"
    }
    
    func create(resource: Resource) -> String {
        return resource.type // or "<type>"
    }
    
    func update(resource: Resource) -> String {
        let type = type.resourceType
        
        return type + "/" + id // or "<type>/<id>"
    }
    
    func delete(id: String, type: Resource.Type) -> String {
        let type = type.resourceType
        
        return type + "/" + id // or "<type>/<id>"
    }
}

Then you would use:

let router = ResourceRouter()

let dataSource = DataSource<Person>(strategy: .router(router), client: client)

dataSource
    .fetch()
    ...

Tests

DataSource with router and client when creating resource invokes execute request on client
DataSource with router and client when creating resource invokes correct method on router
DataSource with router and client when creating resource passes correct parameters to router
DataSource with router and client when creating resource client receives correct data from router for execution
DataSource with router and client when fetching single resource invokes execute request on client
DataSource with router and client when fetching single resource invokes correct method on router
DataSource with router and client when fetching single resource passes correct parameters to router
DataSource with router and client when fetching single resource client receives correct data from router for execution
DataSource with router and client when fetching resource collection invokes execute request on client
DataSource with router and client when fetching resource collection invokes correct method on router
DataSource with router and client when fetching resource collection passes correct parameters to router
DataSource with router and client when fetching resource collection client receives correct data from router for execution
DataSource with router and client when updating resource invokes execute request on client
DataSource with router and client when updating resource invokes correct method on router
DataSource with router and client when updating resource passes correct parameters to router
DataSource with router and client when updating resource client receives correct data from router for execution
DataSource with router and client when deleting resource invokes execute request on client
DataSource with router and client when deleting resource invokes correct method on router
DataSource with router and client when deleting resource passes correct parameters to router
DataSource with router and client when deleting resource client receives correct data from router for execution
DataSource with path and client when creating resource invokes execute request on client
DataSource with path and client when creating resource client receives correct data for execution
DataSource with path and client when creating resource client receives userInfo for execution
DataSource with path and client when fetching single resource invokes execute request on client
DataSource with path and client when fetching single resource client receives correct data for execution
DataSource with path and client when fetching resource collection with custom pagination invokes execute request on client
DataSource with path and client when fetching resource collection with custom pagination client receives correct data for execution
DataSource with path and client when fetching resource collection with page based pagination invokes execute request on client
DataSource with path and client when fetching resource collection with page based pagination client receives correct data for execution
DataSource with path and client when fetching resource collection with offset based pagination invokes execute request on client
DataSource with path and client when fetching resource collection with offset based pagination client receives correct data for execution
DataSource with path and client when fetching resource collection with cursor based pagination invokes execute request on client
DataSource with path and client when fetching resource collection with cursor based pagination client receives correct data for execution
DataSource with path and client when updating resource invokes execute request on client
DataSource with path and client when updating resource client receives correct data for execution
DataSource with path and client when deleting resource invokes execute request on client
DataSource with path and client when deleting resource client receives correct data for execution
Deserializer when deserializing resource collection maps correctly
Deserializer when deserializing single resource and error data provided with source object included in errors maps to errors object
Deserializer when deserializing single resource and error data provided with source object included in errors maps to errors object 2
Deserializer when deserializing document with polymorphic objects in relationships maps correctly
Deserializer when deserializing single resource maps correctly
Paginated DataSource when fetching first page returns first page document
Paginated DataSource when fetching first page when fetching next page returns next page document
Paginated DataSource when fetching first page returns first page document 2
Paginated DataSource when fetching first page when fetching first page of document returns first page document
Paginated DataSource when fetching first page returns first page document 3
Paginated DataSource when fetching first page when appending next page document is appended
Paginated DataSource when fetching first page when appending next page included is appended
Paginated DataSource when fetching first page returns first page document 4
Paginated DataSource when fetching first page when reloading current page receives page
Paginated DataSource when fetching first page returns first page document 5
Paginated DataSource when fetching first page when fetching previous page receives page
Paginated DataSource when fetching first page returns first page document 6
Paginated DataSource when fetching first page when fetching last page returns last page document
Serializer when serializing resource collection maps correctly
Serializer when serializing resource collection returns document data
Serializer when serializing resource collection returns document dictionary
Serializer when serializing single resource maps correctly
Serializer when serializing single resource returns document data
Serializer when serializing single resource returns document dictionary

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT

Files

README.md

Latest commit

History

README.md

File metadata and controls

Vox

The magic behind

Installation

Requirements

Usage

Defining resource

Serializing

Single resource

Resource collection

Nullability

Deserializing

Single resource

Resource collection

Description

Networking

Client protocol

Alamofire client plugin

Installation

Fetching single resource

Fetching resource collection

Creating resource

Updating resource

Deleting resource

Pagination

Pagination on initial request

Custom pagination strategy

Page-based pagination strategy

Offset-based pagination strategy

Cursor-based pagination strategy

Appending next page to current document

Fetching next document page

Fetching previous document page

Fetching first document page

Fetching last document page

Reloading current document page

Custom routing

Tests

Contributing

License