JSONAPI

A Swift package for encoding to- and decoding from JSON API compliant requests and responses.

See the JSON API Spec here: https://jsonapi.org/format/

Quick Start

Clientside

• Basic Example
• Compound Example
• Metadata Example
• Custom Errors Example
• PATCH Example
• Resource Storage Example (using JSONAPI-ResourceStorage)

Serverside

• GET Example
• POST Example

Client+Server

This library works well when used by both the server responsible for serialization and the client responsible for deserialization. Check out the example.

Table of Contents

• JSONAPI
  • Primary Goals
  • Dev Environment
    • Prerequisites
    • Swift Package Manager
    • Xcode project
    • CocoaPods
    • Running the Playground
  • Project Status
  • Server & Client Example
  • Usage
• JSONAPI+Testing
  • Literal Expressibility
  • Resource Object check()
  • Comparisons
• JSONAPI-Arbitrary
• JSONAPI-OpenAPI
• JSONAPI-ResourceStorage

Primary Goals

The primary goals of this framework are:

1. Allow creation of Swift types that are easy to use in code but also can be encoded to- or decoded from JSON API v1.0 Spec compliant payloads without lots of boilerplate code.
2. Leverage Codable to avoid additional outside dependencies and get operability with non-JSON encoders/decoders for free.
3. Do not sacrifice type safety.
4. Be platform agnostic so that Swift code can be written once and used by both the client and the server.
5. Provide human readable error output. The errors thrown when decoding an API response and the results of the JSONAPITesting framework's compare(to:) functions all have digestible human readable descriptions (just use String(describing:)).

Caveat

The big caveat is that, although the aim is to support the JSON API spec, this framework ends up being naturally opinionated about certain things that the API Spec does not specify. These caveats are largely a side effect of attempting to write the library in a "Swifty" way.

If you find something wrong with this library and it isn't already mentioned under Project Status, let me know! I want to keep working towards a library implementation that is useful in any application.

Dev Environment

Prerequisites

1. Swift 6.0+
2. Swift Package Manager

Swift Package Manager

Just include the following in your package's dependencies and add JSONAPI to the dependencies for any of your targets.

.package(url: "https://github.com/mattpolzin/JSONAPI.git", from: "6.0.0")

Deeper Dive

• Project Status
• Server & Client Example
• Usage Documentation

JSONAPI+Testing

The JSONAPI framework is packaged with a test library to help you test your JSONAPI integration. The test library is called JSONAPITesting. You can see JSONAPITesting in action in the Playground included with the JSONAPI repository.

Literal Expressibility

Literal expressibility for Attribute, ToOneRelationship, and Id are provided so that you can easily write test ResourceObject values into your unit tests.

For example, you could create a mock Author (from the above example) as follows

let author = Author(
	id: "1234", // You can just use a String directly as an Id
	attributes: .init(name: "Janice Bluff"), // The name Attribute does not need to be initialized, you just use a String directly.
	relationships: .none,
	meta: .none,
	links: .none
)

Resource Object check()

The ResourceObject gets a check() function that can be used to catch problems with your JSONAPI structures that are not caught by Swift's type system.

To catch malformed JSONAPI.Attributes and JSONAPI.Relationships, just call check() in your unit test functions:

func test_initAuthor() {
	let author = Author(...)
	Author.check(author)
}

Comparisons

You can compare Documents, ResourceObjects, Attributes, etc. and get human-readable output using the compare(to:) methods included with JSONAPITesting.

func test_articleResponse() {
	let endToEndAPITestResponse: SingleArticleDocumentWithIncludes = ...

	let expectedResponse: SingleArticleDocumentWithIncludes = ...

	let comparison = endToEndAPITestResponse.compare(to: expectedResponse)

	XCTAssert(comparison.isSame, String(describing: comparison))
}

JSONAPI-Arbitrary

The JSONAPI-Arbitrary library provides SwiftCheck Arbitrary conformance for many of the JSONAPI types.

See https://github.com/mattpolzin/JSONAPI-Arbitrary for more information.

JSONAPI-OpenAPI

The JSONAPI-OpenAPI library generates OpenAPI compliant JSON Schema for models built with the JSONAPI library. If your Swift code is your preferred source of truth for API information, this is an easy way to document the response schemas of your API.

JSONAPI-OpenAPI also has experimental support for generating JSONAPI Swift code from Open API documentation (this currently lives on the feature/gen-swift branch).

See https://github.com/mattpolzin/JSONAPI-OpenAPI for more information.

JSONAPI-ResourceStorage

The JSONAPI-ResourceStorage package has two very early stage modules supporting storage and retrieval of JSONAPI.ResourceObjects. Please consider these modules to be more of examples of two directions you could head in than anything else.

https://github.com/mattpolzin/JSONAPI-ResourceStorage