https://github.com/eygraber/jsonapi-kotlin

A Kotlin Multiplatform kotlinx.serialization library for working with JSON:API
https://github.com/eygraber/jsonapi-kotlin

json-api kotlin kotlin-multiplatform kotlinx-serialization

Last synced: about 2 months ago
JSON representation

A Kotlin Multiplatform kotlinx.serialization library for working with JSON:API

• Host: GitHub
• URL: https://github.com/eygraber/jsonapi-kotlin
• Owner: eygraber
• License: mit
• Created: 2024-06-07T04:02:23.000Z (7 months ago)
• Default Branch: master
• Last Pushed: 2024-11-05T19:14:48.000Z (about 2 months ago)
• Last Synced: 2024-11-05T20:28:52.951Z (about 2 months ago)
• Topics: json-api, kotlin, kotlin-multiplatform, kotlinx-serialization
• Language: Kotlin
• Homepage:
• Size: 230 KB
• Stars: 15
• Watchers: 1
• Forks: 1
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • Changelog: changelog_config.json
  • License: LICENSE

Awesome Lists containing this project

• awesome-list - eygraber/jsonapi-kotlin - A Kotlin Multiplatform kotlinx.serialization library for working with JSON:API (Kotlin)

README

        
# JSON:API Kotlin

`jsonapi-kotlin` is a Kotlin Multiplatform library for working with [JSON:API](https://jsonapi.org/) documents.

It integrates with [kotlinx-serialization](https://github.com/Kotlin/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](https://github.com/Kotlin/kotlinx.serialization).

## Gradle

```kotlin

repositories {

  mavenCentral()

}

dependencies {

  implementation("com.eygraber:jsonapi-kotlin:0.2.2")

  

  // kotlinx.serialization json is used for the actual serialization

  implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:")

}

```

## Usage

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

```kotlin

val json = Json()

val document = json.decodeFromString(string)

// OR

val document = json.decodeFromJsonElement(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:

```kotlin

val resource = json.decodeFromString(string)

val resources = json.decodeFromString(string)

val resourceIdentifier = json.decodeFromString(string)

val resourceIdentifiers = json.decodeFromString(string)

val meta = json.decodeFromString(string)

val errors = json.decodeFromString(string)

```

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

```kotlin

json.encodeToString(document)

// OR

json.encodeToJsonElement(document)

```

## Builders

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

```kotlin

JsonApiDocument

  .builder()

  .identifier(

    type = "articles",

    id = JsonApiId("1"),

  ) {

    meta {

      put("created", "2019-01-01T00:00:00Z")

    }

  }

  .build()

```

See more examples at [JsonApiBuilderTest](./jsonapi/src/commonTest/kotlin/com/eygraber/jsonapi/JsonApiBuilderTest.kt).

## In Progress

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