jsonapi-kotlin

Library facilitates easy serialization and deserialization of JSON:API documents into native types, supporting builder functions for document creation, with ongoing enhancements for domain type extraction.

#serializer
#serialization
#ksp
#kotlin-serialization
#json
#code-generation

Suggest an edit

Android JVMJVMKotlin/NativeWasmJS

GitHub stars22

Authorseygraber

Open issues2

LicenseMIT License

Creation dateover 1 year ago

Last activity14 days ago

Latest release0.2.3 (over 1 year ago)

GitHub repository Wiki page

JSON:API Kotlin

jsonapi-kotlin is a Kotlin Multiplatform library for working with JSON:API documents.

It integrates with kotlinx-serialization to allow deserializing String and JsonObject representations of a JSON:API document into a Kotlin type, and for serializing the Kotlin type to a String or JsonObject.

You can use this library with all targets supported by kotlinx-serialization.

Gradle

repositories {
  mavenCentral()
}

dependencies {
  implementation("com.eygraber:jsonapi-kotlin:0.2.3")
  
  // kotlinx.serialization json is used for the actual serialization
  implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:<latest version>")
}

Usage

With a kotlinx.serialization.json.Json instance, you can decode a JsonApiDocument from a String or JsonObject:

val json = Json()

val document = json.decodeFromString<JsonApiDocument>(string)

// OR

val document = json.decodeFromJsonElement<JsonApiDocument>(jsonObject)

This will return a generic JsonApiDocument. If you know the specific type of JsonApiDocument you are working with, you can specify it explicitly so that you don't need to cast:

val resource = json.decodeFromString<JsonApiDocument.Resource>(string)
val resources = json.decodeFromString<JsonApiDocument.Resources>(string)
val resourceIdentifier = json.decodeFromString<JsonApiDocument.Identifier>(string)
val resourceIdentifiers = json.decodeFromString<JsonApiDocument.Identifiers>(string)
val meta = json.decodeFromString<JsonApiDocument.Meta>(string)
val errors = json.decodeFromString<JsonApiDocument.Errors>(string)

You can also encode the JsonApiDocument to a String or JsonObject:

json.encodeToString(document)

// OR

json.encodeToJsonElement(document)

Builders

There are convenient builder functions available to assist in creating a JsonApiDocument from scratch:

JsonApiDocument
  .builder()
  .identifier(
    type = "articles",
    id = JsonApiId("1"),
  ) {
    meta {
      put("created", "2019-01-01T00:00:00Z")
    }
  }
  .build()

See more examples at JsonApiBuilderTest.

In Progress

There is a KSP artifact being worked on that will make it easier to extract your domain types from a JsonApiDocument.