{"id":25293601,"url":"https://github.com/qvantel/jsonapi-scala","last_synced_at":"2025-10-28T01:31:54.758Z","repository":{"id":55013337,"uuid":"87530118","full_name":"qvantel/jsonapi-scala","owner":"qvantel","description":"jsonapi.org library for scala","archived":false,"fork":false,"pushed_at":"2024-02-09T09:04:47.000Z","size":357,"stargazers_count":22,"open_issues_count":1,"forks_count":11,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-03-26T20:22:06.492Z","etag":null,"topics":["jsonapi","scala"],"latest_commit_sha":null,"homepage":null,"language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qvantel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2017-04-07T09:37:38.000Z","updated_at":"2024-04-15T13:01:30.717Z","dependencies_parsed_at":"2024-04-15T13:01:29.280Z","dependency_job_id":"d6a9a6c6-49e6-448a-8015-6cb121d7cd5f","html_url":"https://github.com/qvantel/jsonapi-scala","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qvantel%2Fjsonapi-scala","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qvantel%2Fjsonapi-scala/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qvantel%2Fjsonapi-scala/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qvantel%2Fjsonapi-scala/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qvantel","download_url":"https://codeload.github.com/qvantel/jsonapi-scala/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238579794,"owners_count":19495551,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jsonapi","scala"],"created_at":"2025-02-13T01:54:58.148Z","updated_at":"2025-10-28T01:31:49.393Z","avatar_url":"https://github.com/qvantel.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [JSON:API v1.1](http://jsonapi.org/) implementation in scala\n\n[![CI](https://github.com/qvantel/jsonapi-scala/actions/workflows/ci.yml/badge.svg)](https://github.com/qvantel/jsonapi-scala/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/qvantel/jsonapi-scala/branch/master/graph/badge.svg)](https://codecov.io/gh/qvantel/jsonapi-scala)\n[![jsonapi-scala-core Scala version support](https://index.scala-lang.org/qvantel/jsonapi-scala/jsonapi-scala-core/latest-by-scala-version.svg?platform=jvm)](https://index.scala-lang.org/qvantel/jsonapi-scala/jsonapi-scala-core)\n\n## Features\n* Automatic generation of jsonapi json writers with relationship handling for case classes\n\n## Requirements\n* Tested to work on Scala 2.12.10 or 2.13.3\n* If you are using Scala 2.12 use the macro paradise plugin. Add `addCompilerPlugin(\"org.scalamacros\" % \"paradise\" % \"2.1.0\" cross CrossVersion.full)` into your build.sbt somewhere.  \n  If you are using Scala 2.13 you should instead use the compiler flag `-Ymacro-annotations`.  \n  An example for handling cross-compiling with both can be found in `project/MacrosCompiler`.\n\n## Releasing\n\nReleasing is done automatically using [sbt-ci-release](https://github.com/sbt/sbt-ci-release).\n\n### Example\n```scala\nimport _root_.spray.json.DefaultJsonProtocol._\nimport com.qvantel.jsonapi._\n\nimplicit val apiRoot: ApiRoot = ApiRoot(None)\n\n@jsonApiResource final case class Employee(id: String, name: String)\n@jsonApiResource final case class Company(id: String, name: String, employees: ToMany[Employee])\n\nval acme = Company(\"1\", \"acme\", ToMany.loaded(Seq(Employee(\"1\", \"number one 1\"))))\n\nval json = rawOne(acme)\nval parsed = readOne[Company](json, Set(\"employees\"))\n\nacme == parsed // true\n```\n\nor see https://github.com/Doikor/jsonapi-scala-example\n\n### Known issues\n  * loop handing on reader side (relationship path has to be given manually)\n\n\n## JsonApiClient\n\nThere is a very generic JsonApiClient interface for implementing a simple client \ninterface for handling the http query writing side of this\n\nThe subproject \"pekko-client\" has an implementation of this using pekko-http\n\nThe subproject \"http4s-client\" has an implementation of this using http4s\n\n### Usage\n\n```scala\nimport cats.data.OptionT\nimport com.qvantel.jsonapi.JsonApiClient\n\nval jac = JsonApiClient.instance // won't work if you don't have an actual implementations stuff in scope. See setup.\n\nval one: IO[Option[BillingAccount]] = jac.one[BillingAccount](\"ba1\") \nval many: IO[List[BillingAccount]] = jac.many[BillingAccount](Set(\"ba1\", \"ba2\"))\n\n// can also load includes at the same time\nval withIncludes = jac.one[BillingAccount](\"ba1\", Set(\"customer-account\"))\n\n// includes can also be loaded on their own with a method\nval ba: OptionT[IO, BillingAccount]  = OptionT(jac.one[BillingAccount](\"ba\"))\nval ca: OptionT[IO, CustomerAccount] = ba.semiflatMap(_.customerAccount.load)\n\n// filtering support\nval filtered = jac.filter[BillingAccount](\"some nice filter string here\")\n```\n\n### Setup\n\n#### pekko-http client\n```scala\n// needs ActorSystem and Materializer for pekko-http\n// the ApiEndPoint is used to as the \"root\" where to launch queries\nimport io.lemonlabs.uri.typesafe.dsl._\nimport org.apache.pekko.actor.ActorSystem\nimport org.apache.pekko.stream.Materializer\nimport com.qvantel.jsonapi.ApiEndpoint\nimport com.qvantel.jsonapi.JsonApiClient\nimport com.qvantel.jsonapi.client.pekko.PekkoClient._\n\nimplicit val system: ActorSystem  = ActorSystem()\nimplicit val materializer: Materializer     = Materializer(system)\nimplicit val endpoint: ApiEndpoint = ApiEndpoint.Static(\"http://localhost:8080/api\")\n\nval jac = JsonApiClient.instance\n```\n\n#### akka-http client (to be deprecated in favor of pekko-http)\n\n```scala\n// needs ActorSystem and Materializer for akka-http\n// the ApiEndPoint is used to as the \"root\" where to launch queries\nimport io.lemonlabs.uri.typesafe.dsl._\nimport akka.actor.ActorSystem\nimport akka.stream.ActorMaterializer\nimport com.qvantel.jsonapi.ApiEndpoint\nimport com.qvantel.jsonapi.JsonApiClient\nimport com.qvantel.jsonapi.client.akka.AkkaClient._\n\nimplicit val system: ActorSystem  = ActorSystem()\nimplicit val materializer: ActorMaterializer = ActorMaterializer()\nimplicit val endpoint: ApiEndpoint = ApiEndpoint.Static(\"http://localhost:8080/api\")\n\nval jac = JsonApiClient.instance\n```\n\n#### http4s client\nSetup for http4s client\n```scala\nimport io.lemonlabs.uri.typesafe.dsl._\nimport org.http4s.client.Client\nimport org.http4s.client.blaze.Http1Client\nimport cats.effect.IO\nimport com.qvantel.jsonapi.ApiEndpoint\nimport com.qvantel.jsonapi.JsonApiClient\n\nimport com.qvantel.jsonapi.client.http4s.Http4sClient._\nimport com.qvantel.jsonapi.client.http4s.JsonApiInstances._\n\n\nimplicit val endpoint: ApiEndpoint = ApiEndpoint.Static(\"http://localhost:8080/api\")\n\nimplicit val client: Client[IO] = Http1Client[IO]().unsafeRunSync()\n\nval jac = JsonApiClient.instance\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqvantel%2Fjsonapi-scala","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqvantel%2Fjsonapi-scala","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqvantel%2Fjsonapi-scala/lists"}