IzzyParser iOS

IzzyParser is a library for serializing and deserializing JSON API objects.

Installation

Swift Package Manager

1. Using Xcode 11 or higher go to File > Swift Packages > Add Package Dependency
2. Paste the project URL: https://github.com/undabot/izzyparser-ios.git
3. Click on next, select the project target and click finish
4. Import IzzyParser

Cocoapods

CocoaPods is a dependency manager for Cocoa projects To integrate IzzyParser into your Xcode project using CocoaPods, specify it in your Podfile:

target '<Your Target Name>' do
    pod 'IzzyParser'
end

Then, run the following command:

$ pod install

Usage

Defining resource

All resources MUST inherit Resource class.

Basic resource:

class Author: Resource {
    
    override class var type: String {
        return "people"
    }
    
    required init(id: String) {
        super.init(id: id)
    }
}

Resource with customKeys for serialization and typesForKeys for deserialization:

class Article: Resource {
    @objc var title: String = ""
    @objc var author: Author?
    @objc var comment: Comment?
    
    override class var type: String {
        return "articles"
    }
    
    // Custom coding keys
    override public class var customKeys: [String: String] {
        return ["komentar": "comment"]
    }
    
    override public class var typesForKeys: [String: CustomObject.Type] {
        return ["komentar": Comment.self]
    }
    
    init(id: String, title: String, author: Author, comment: Comment? = nil) {
        self.title = title
        self.author = author
        self.comment = comment
        super.init(id: id)
    }
    
    required init(id: String) {
        super.init(id: id)
    }
}

Object with custom deserializer:

class Comment: NSObject, CustomObject {
    @objc var id: String
    @objc var content: String
    required init(objectJson: [String: Any]) {
        self.id = objectJson["id"] as? String ?? ""
        self.content = objectJson["content"] as? String ?? ""
    }
}

Codable custom object:

class CodableComment: NSObject, CodableCustomObject {
    var id: String?
    var content: String?
}

Registering resources

All resources MUST be registered to Izzy instance.

// Creating resource map
let resourceMap: [Resource.Type] = [
    Article.self,
    Author.self
]

// Registering resources
let izzy = Izzy()
izzy.registerResources(resources: resourceMap)

Developers often forget to register resources to resource map. If resource is not registered, deserializer will return nil for missing object (it is wanted behaviour). But, you can turn on debug mode while developing, so Izzy will throw an error if resource is not registered. Don’t enable debug mode for production code because it will cause crashes, it should be used only for debugging purpose - so that you can detect what resources are not registered.

// Registering resources
let izzy = Izzy()
izzy.isDebugModeOn = true
izzy.registerResources(resources: resourceMap)

Serializing

Serializing single resource:

// Article serialization
let author = Author(id: "authorID")
let article = Article(id: "articleID", title: "Article title", author: author)

let serializedArticle = izzy.serialize(resource: article)

Output:

// Serialized article JSON:
/**
    {
      "data" : {
        "attributes" : {
          "title" : "Article title"
        },
        "id" : "articleID",
        "type" : "articles",
        "relationships" : {
          "author" : {
            "data" : {
              "id" : "authorID",
              "type" : "people"
            }
          }
        }
      }
    }
*/

Serializing single resource with custom property serialization:

// Article serialization with custom author serialization
let customRelationshipDict: [String: Any] = [
    "name": "John",
    "surname": "Smith",
    "age": NSNull()
]

serializedArticle = izzy.serializeCustom(resource: article, relationshipKey: "author", relationshipValue: customRelationshipDict)

Output:

// Serialized article JSON:
/**
    {
      "data" : {
        "attributes" : {
          "title" : "Article title"
        },
        "id" : "articleID",
        "type" : "articles",
        "relationships" : {
          "author" : {
            "name" : "John",
            "surname" : "Smith",
            "age" : null
          }
        }
      }
    }
*/

Serializing resource collection:

let author = Author(id: "authorID")
let article = Article(id: "articleID", title: "Article title", author: author)

let serializedResourceCollection = izzy.serialize(resourceCollection: [article, article])

Output:

// Serialized resource collection:
 /**
     {
      "data" : [
        {
          "attributes" : {
            "title" : "Article title"
          },
          "id" : "articleID",
          "type" : "articles",
          "relationships" : {
            "author" : {
              "data" : {
                "id" : "authorID",
                "type" : "people"
              }
            }
          }
        },
        {
          "attributes" : {
            "title" : "Article title"
          },
          "id" : "articleID",
          "type" : "articles",
          "relationships" : {
            "author" : {
              "data" : {
                "id" : "authorID",
                "type" : "people"
              }
            }
          }
        }
      ]
    }
 */

Deserializing

Deserializing single resource:

Input JSON:

// JSON data:
/**
    {
    "data": {
        "type": "articles",
        "id": "1",
        "attributes": {
            "title": "Rails is Omakase",
            "komentar": {
                "id": "11",
                "content": "Custom content"
            }

        },
        "relationships": {
            "author": {
                "links": {
                    "self": "/articles/1/relationships/author",
                    "related": "/articles/1/author"
                },
                "data": { "type": "people", "id": "9" }
            }
        }
    }
}
*/

// Article deserialization
do {
    let document: Document<Article> = try izzy.deserializeResource(from: data)
    let article = document.data
    
    let id = article?.id
} catch let error {
    print(error.localizedDescription)
}

Deserializing resource collection:

// Article deserialization
do {
    let document: Document<[Article]> = try izzy.deserializeCollection(data)
    let articles = document.data
} catch let error {
    print(error.localizedDescription)
}

Resource with array of custom objects:

Input JSON:

/**
{
    "data": {
        "type": "subscription",
        "id": "1",
        "attributes": {
            "title": "Very nice subscription!",
            "prices": [{
                "type:": "monthly",
                "value": "1"
            },
            {
                "type:": "onetime",
                "value": "10"
            }]
        }
    }
}
*/

@objcMembers class SubscriptionResource: Resource {
    
    var title: String?
    var prices: [Price]?

    override class var type: String {
        return "subscription"
    }

    override class var typesForKeys: [String : CustomObject.Type] {
        return ["prices": Price.self]
    }
}

struct Price: Codable {
    var value: String?
    var type: String?
}

License

IzzyParser is released under the MIT license. See LICENSE for details.