Lightweight JSON:API parser that flattens complex JSON:API structure and turns it into simple JSON and vice versa.
It works by transferring Dictionary to Dictionary, so you can use Codable, Unbox, Wrap, ObjectMapper or any other object mapping tool that you prefer.
For given example of JSON object:
{
"data": {
"id": "1",
"type": "users",
"attributes": {
"email": "[email protected]",
"username": "john"
}
}
}to parse it to simple JSON use:
let jsonApiObject: [String: Any] = ...
let simpleObject: [String: Any]
do {
simpleObject = try JapxKit.Decoder.jsonObject(withJSONAPIObject: jsonApiObject)
} catch {
print(error)
}and parser will convert it to object where all properties inside attributes object will be flattened to the root of data object:
{
"data": {
"email": "[email protected]",
"id": "1",
"username": "john",
"type": "users"
}
}Simple Article object which has its Author:
{
"data": [
{
"type": "articles",
"id": "1",
"attributes": {
"title": "JSON API paints my bikeshed!",
"body": "The shortest article. Ever.",
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
},
"relationships": {
"author": {
"data": {
"id": "42",
"type": "people"
}
}
}
}
],
"included": [
{
"type": "people",
"id": "42",
"attributes": {
"name": "John",
"age": 80,
"gender": "male"
}
}
]
}will be flattened to:
{
"data": [
{
"updated": "2015-05-22T14:56:28.000Z",
"author": {
"age": 80,
"id": "42",
"gender": "male",
"type": "people",
"name": "John"
},
"id": "1",
"title": "JSON API paints my bikeshed!",
"created": "2015-05-22T14:56:29.000Z",
"type": "articles",
"body": "The shortest article. Ever."
}
]
}All nested object which do not have keys defined in JSON:API Specification will be left inside root object intact (same goes for links and meta objects):
{
"data": [
{
"type": "articles",
"id": "3",
"attributes": {
"title": "JSON API paints my bikeshed!",
"body": "The shortest article. Ever.",
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
}
],
"meta": {
"total-pages": 13
},
"links": {
"self": "http://example.com/articles?page[number]=3&page[size]=1",
"first": "http://example.com/articles?page[number]=1&page[size]=1",
"prev": "http://example.com/articles?page[number]=2&page[size]=1",
"next": "http://example.com/articles?page[number]=4&page[size]=1",
"last": "http://example.com/articles?page[number]=13&page[size]=1"
},
"additional": {
"info": "My custom info"
}
}Parsed JSON:
{
"data": [
{
"updated": "2015-05-22T14:56:28.000Z",
"id": "3",
"title": "JSON API paints my bikeshed!",
"created": "2015-05-22T14:56:29.000Z",
"type": "articles",
"body": "The shortest article. Ever."
}
],
"meta": {
"total-pages": 13
},
"links": {
"prev": "http://example.com/articles?page[number]=2&page[size]=1",
"first": "http://example.com/articles?page[number]=1&page[size]=1",
"next": "http://example.com/articles?page[number]=4&page[size]=1",
"self": "http://example.com/articles?page[number]=3&page[size]=1",
"last": "http://example.com/articles?page[number]=13&page[size]=1"
},
"additional": {
"info": "My custom info"
}
}For defining which nested object you want to parse, you can use includeList parameter. For example:
{
"data": {
"type": "articles",
"id": "1",
"attributes": {
"title": "JSON API paints my bikeshed!",
"body": "The shortest article. Ever.",
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
},
"relationships": {
"author": {
"data": {
"id": "42",
"type": "people"
}
}
}
},
"included": [
{
"type": "people",
"id": "42",
"attributes": {
"name": "John",
"age": 80,
"gender": "male"
},
"relationships": {
"article": {
"data": {
"id": "1",
"type": "articles"
}
}
}
}
]
}Article and Author can be matched using include reference, as defined in JSON:API Specification:
let includeList: String = "author.article.author"
let jsonApiObject: [String: Any] = ...
let recursiveObject: [String: Any] = try JapxKit.Decoder.jsonObject(with: jsonApiObject, includeList: includeList)Parsed JSON:
{
"data": {
"type": "articles",
"id": "1",
"title": "JSON API paints my bikeshed!",
"body": "The shortest article. Ever.",
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z",
"author": {
"type": "people",
"id": "42",
"name": "John",
"age": 80,
"gender": "male",
"article": {
"type": "articles",
"id": "1",
"title": "JSON API paints my bikeshed!",
"body": "The shortest article. Ever.",
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z",
"author": {
"type": "people",
"id": "42",
"name": "John",
"age": 80,
"gender": "male"
}
}
}
}
}Japx comes with wrapper for Swift Codable.
Since JSON:API object can have multiple additional fields like meta, links or pagination info, its real model needs to be wrapped inside data object. For easier parsing, also depending on your API specification, you should create wrapping native object which will contain your generic JSON model:
struct JapxResponse<T: Codable>: Codable {
let data: T
// ... additional info like: meta, links, pagination...
}
struct User: JapxCodable {
let id: String
let type: String
let email: String
let username: String
}
let userResponse: JapxResponse<User> = try JapxDecoder().decode(JapxResponse<User>.self, from: data)
let user: User = userResponse.datawhere JapxDecodable and JapxEncodable are defined in JapxCodable file as:
/// Protocol that extends Decodable with required properties for JSON:API objects
protocol JapxDecodable: Decodable {
var type: String { get }
var id: String { get }
}
/// Protocol that extends Encodable with required properties for JSON:API objects
protocol JapxEncodable: Encodable {
var type: String { get }
}Japx also comes with wrapper for Alamofire and Codable which can be installed as described in installation chapter.
Use responseCodableJSONAPI method on DataRequest which will pass serialized response in callback. Also, there is keyPath argument to extract only nested data object. So, if you don't need any additional info from API side except plain data, than you can create simple objects, without using wrapping objects/structs.
struct User: JapxCodable {
let id: String
let type: String
let email: String
let username: String
}
Alamofire
.request(".../api/v1/users/login", method: .post, parameters: [...])
.validate()
.responseCodableJSONAPI(keyPath: "data", completionHandler: { (response: DataResponse<User>) in
switch response.result {
case .success(let user):
print(user)
case .failure(let error):
print(error)
}
})Japx also comes with wrapper for Alamofire, Codable and RxSwift which can be installed as described in installation chapter.
Use responseCodableJSONAPI method from .rx extension on DataRequest which will return Single with serialized response.
let loginModel: LoginModel = ...
let executeLogin: ([String: Any]) throws -> Single<User> = {
return Alamofire
.request(".../api/v1/users/login", method: .post, parameters: $0)
.validate()
.rx.responseCodableJSONAPI(keyPath: "data")
}
return Single.just(loginModel)
.map { try JapxEncoder().encode($0) }
.flatMap(executeLogin)Japx is available through CocoaPods. To install it, simply add the following line to your Podfile:
pod 'Japx'We've also added some more functionalites like Alamofre or Moya for networking, Rx for reactive programming approach, Objective-C support:
# Alamofire
pod 'Japx/Alamofire'
# Alamofire and RxSwift
pod 'Japx/RxAlamofire'
# Moya
pod 'Japx/Moya'
# Moya and RxSwift
pod 'Japx/RxMoya'
# Objective-C
pod 'Japx/ObjC'Unlike with other dependency managers below, you should always use:
import Japxregardless of which custom integration you've picked.
platform :ios, '10.0'
use_frameworks!
target 'MyApp' do
pod 'Japx/RxMoya'
endAdd the dependency to your Package.swift and use in your target
dependencies: [
.package(url: "https://github.com/infinum/Japx.git", .upToNextMajor(from: "4.0.0"))
]Sample Package.swift
let package = Package(
name: "YourDependency",
products: [
.library(name: "YourDependency", targets: ["YourDependency"])
],
dependencies: [
.package(url: "https://github.com/infinum/Japx.git", .upToNextMajor(from: "4.0.0")),
],
targets: [
.target(
name: "YourDependency",
dependencies: [.product(name: "Japx", package: "Japx")]
)
]
)We've also added some more functionalites like Alamofre or Moya for networking, Rx for reactive programming approach:
// Alamofire
.product(name: "JapxAlamofire", package: "Japx")
// Alamofire and RxSwift
.product(name: "JapxRxAlamofire", package: "Japx")
// Moya
.product(name: "JapxMoya", package: "Japx")
// Moya and RxSwift
.product(name: "JapxRxMoya", package: "Japx")Depending on which product you've picked, you'll have to import different modules:
// Pure Japx
import Japx
// Alamofire
import JapxAlamofire
// Alamofire and RxSwift
import JapxRxAlamofire
// Moya
import JapxMoya
// Moya and RxSwift
import JapxRxMoyaRun carthage update --use-xcframeworks and import desired integration. Pure Japx doesn't have any dependencies.
Imports work same as for Swift Package Manager, depending on which integration you've picked.
NOTE: Moya integration is currently not supported via Carthage since latest Moya build won't build with Carthage. More info here.
Example project of Japx networking using Codable and Alamofire can be found in Nuts And Bolts repository with commonly used code. Example will cover how to handle basic CRUD (Create, Read, Update, Delete) operations with Japx and JSON:API format. To run the example, clone the repository, open the Catalog.xcworkspace, run Catalog app and navigate to the Japx Networking section.
In this repository there is also a simple example project, to run it open Japx.xcodeproj and inspect Example directory and Japx_Example scheme.
Basic integrations with Cocoapods (run pod install), Swift Package Manager and Carthage can be found inside Examples directory.
- Vlaho Poluta, [email protected]
- Filip Gulan, [email protected]
Maintained by Infinum
Japx is available under the MIT license. See the LICENSE file for more info.
Relationships can also include metadata. The original implementation of Japx didn't make it possible. We've added additional code to parse it in a JapxCodable object. All you need to do is add a Codable object property named as the relationship key + "Meta" keyword.
For example, for such a JSON:
{
"data": [
{
"type": "articles",
"id": "1",
"attributes": {
"title": "JSON API paints my bikeshed!",
"body": "The shortest article. Ever.",
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
},
"relationships": {
"author": {
"data": {
"id": "42",
"type": "people"
},
"meta": {
"totalBooks": 2
}
}
}
}
],
"included": [
{
"type": "people",
"id": "42",
"attributes": {
"name": "John",
"age": 80,
"gender": "male"
}
}
]
}
A proper model for an article to get total books should be:
struct Article: JapxCodable {
let id: String
let type: String
let author: Author
let authorMeta: AuthorMeta
}
struct AuthorMeta: Codable {
let totalBooks: Int
}
And object in an array can also have metadata, which is sent alongside attributes and relationships. For example:
{
"data": [
{
"type": "articles",
"id": "1",
"attributes": {
"title": "JSON API paints my bikeshed!",
"body": "The shortest article. Ever.",
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
},
"relationships": {
"author": {
"data": {
"id": "42",
"type": "people"
}
}
},
"meta": {
"myVote": 1
}
}
],
"included": [
{
"type": "people",
"id": "42",
"attributes": {
"name": "John",
"age": 80,
"gender": "male"
}
}
]
}
A proper model for an article to get my vote should be:
struct Article: JapxCodable {
let id: String
let type: String
let author: Author
let meta: ArticleMeta
}
struct ArticleMeta: Codable {
let myVote: Int
}