Japx

Japx is a lightweight JSON:API parser designed to flatten complex JSON:API structures into simple JSON and vice versa.

It operates by transforming data between Dictionary objects. This allows you to use any object mapping tool you prefer, such as Codable, Unbox, Wrap, or ObjectMapper, on the resulting flattened data.

To install the core Japx library, add the following line to your Podfile:

pod 'Japx'

Japx also provides specialized subspecs for networking and reactive programming. You can install these by specifying the subspec name:

• Japx/Alamofire: Integration with Alamofire
• Japx/RxAlamofire: Integration with Alamofire and RxSwift
• Japx/Moya: Integration with Moya
• Japx/RxMoya: Integration with Moya and RxSwift
• Japx/ObjC: Objective-C support

Note: Regardless of which subspec you install, you should always use import Japx in your Swift code for the core functionality.

platform :ios, '10.0'
use_frameworks!

target 'MyApp' do
  pod 'Japx/RxMoya'
end

Japx provides an extension for Alamofire to simplify decoding JSON:API responses directly from a DataRequest.

Use the responseCodableJSONAPI(keyPath:completionHandler:) method. The keyPath argument allows you to specify which part of the JSON to extract (usually "data") so you can decode directly into your model without needing a wrapper struct.

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)
        }
    })

For reactive programming, Japx provides an extension for Alamofire's .rx property.

Use rx.responseCodableJSONAPI(keyPath:) on a DataRequest to return a Single containing your decoded model. This is useful when chaining network requests with other reactive operations.

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)

Use JapxKit.Decoder.jsonObject(withJSONAPIObject:) to convert a standard JSON:API object into a flattened dictionary. This process moves all properties from the attributes object to the root of the data object, making it easier to work with simple key-value pairs.

Input Example:

{
    "data": {
        "id": "1",
        "type": "users",
        "attributes": {
            "email": "john@infinum.co",
            "username": "john"
        }
    }
}

Output Example:

{
    "data": {
        "email": "john@infinum.co",
        "id": "1",
        "username": "john",
        "type": "users"
    }
}

let jsonApiObject: [String: Any] = ...
let simpleObject: [String: Any]

do {
    simpleObject = try JapxKit.Decoder.jsonObject(withJSONAPIObject: jsonApiObject)
} catch {
    print(error)
}

To parse nested relationships and objects found in the included array, use JapxKit.Decoder.jsonObject(with:includeList:). You provide an includeList string representing the relationship path (e.g., "author.article.author") to tell the parser which nested objects to match and flatten into the main data tree.

Example Usage:

let includeList: String = "author.article.author"
let jsonApiObject: [String: Any] = ...
let recursiveObject: [String: Any] = try JapxKit.Decoder.jsonObject(with: jsonApiObject, includeList: includeList)

Ensure your environment meets the following minimum requirements:

• iOS: 10.0+
• macOS: 10.12+
• Swift: 5.0+