type-safe json-rpc api

Armadillo

London, 2022

We are hiring :)

fully decentralized remote working organisation
software development based on research papers
creators of cardano, first PoS blockchain built using evidence-based methods
established collaboration with recognized universities such as Edinburgh and Stanford

scala

haskell

typescript

agda

How it started?

a requirement to provide json-rpc api
how do we document that api?
how to keep that documentation up-to-date?

JSON-RPC protocol

created in 2005 as a JSON based alternative to XML-RPC protocol
last revision - 2.0 from 2013
transport layer agnostic
mainly used for inter-process communication
generally quite simple, but there as some caveats

JSON-RPC protocol

--> data sent to Server
<-- data sent to Client

Basic request:

--> {
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

https://www.jsonrpc.org/specification

JSON-RPC protocol

--> data sent to Server
<-- data sent to Client

Basic request:

--> {
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

https://www.jsonrpc.org/specification

JSON-RPC protocol

--> data sent to Server
<-- data sent to Client

Basic request:

--> {
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

https://www.jsonrpc.org/specification

JSON-RPC protocol

--> data sent to Server
<-- data sent to Client

Basic request:

--> {
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

https://www.jsonrpc.org/specification

JSON-RPC protocol

--> data sent to Server
<-- data sent to Client

Basic request:

--> {
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

https://www.jsonrpc.org/specification

JSON-RPC protocol

--> data sent to Server
<-- data sent to Client

Basic request:

--> {
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

https://www.jsonrpc.org/specification

JSON-RPC protocol

--> data sent to Server
<-- data sent to Client

Basic request:

--> {
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

https://www.jsonrpc.org/specification

JSON-RPC protocol

--> data sent to Server
<-- data sent to Client

Basic request:

--> {
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

https://www.jsonrpc.org/specification

JSON-RPC protocol

--> data sent to Server
<-- data sent to Client

Request with named parameters:

--> {
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":{
      "subtrahend":23,
      "minuend":42
   },
   "id":3
}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

https://www.jsonrpc.org/specification

JSON-RPC protocol

--> data sent to Server
<-- data sent to Client

A notification:

--> {
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":{
      "subtrahend":23,
      "minuend":42
   }
}

https://www.jsonrpc.org/specification

JSON-RPC protocol

--> data sent to Server
<-- data sent to Client

Batch request:

--> [
        {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
        {"jsonrpc": "2.0", "method": "subtract", "params": [42,23], "id": "2"},
    ]
<-- [
        {"jsonrpc": "2.0", "result": 7, "id": "1"},
        {"jsonrpc": "2.0", "result": 19, "id": "2"},
    ]

https://www.jsonrpc.org/specification

JSON-RPC protocol

--> data sent to Server
<-- data sent to Client

Batch request with a notification:

--> [
	{"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
        {"jsonrpc": "2.0", "method": "notify_hello", "params": ["hello"]},
    ]
<-- [
        {"jsonrpc": "2.0", "result": 7, "id": "1"},
    ]

https://www.jsonrpc.org/specification

Our goals

always up-to-date, automatically generated documentation
fully support JSON-RPC 2.0 specification
express endpoint as values
ability to run it side-by-side with legacy code
integration with multiple json libraries
integration with multiple http servers

Why just not use tapir?

HTTP POST    /
{
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}

HTTP POST    /
{
   "jsonrpc":"2.0",
   "method":"sum",
   "params":[
      42,
      23
   ],
   "id":1
}

Our goals

always up-to-date, automatically generated documentation
fully support JSON-RPC 2.0 specification
express endpoint as values
ability to run it side-by-side with legacy code
integration with multiple json libraries
integration with multiple http servers

Why just not use tapir?

HTTP POST    /
{
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}

HTTP POST    /
{
   "jsonrpc":"2.0",
   "method":"sum",
   "params":[
      42,
      23
   ],
   "id":1
}

val jsonRpc = endpoint

Our goals

always up-to-date, automatically generated documentation
fully support JSON-RPC 2.0 specification
express endpoint as values
ability to run it side-by-side with legacy code
integration with multiple json libraries
integration with multiple http servers

Why just not use tapir?

HTTP POST    /
{
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}

HTTP POST    /
{
   "jsonrpc":"2.0",
   "method":"sum",
   "params":[
      42,
      23
   ],
   "id":1
}

val jsonRpc = endpoint.post

Our goals

always up-to-date, automatically generated documentation
fully support JSON-RPC 2.0 specification
express endpoint as values
ability to run it side-by-side with legacy code
integration with multiple json libraries
integration with multiple http servers

Why just not use tapir?

HTTP POST    /
{
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}

HTTP POST    /
{
   "jsonrpc":"2.0",
   "method":"sum",
   "params":[
      42,
      23
   ],
   "id":1
}

val jsonRpc = endpoint.post.in(jsonBody[JsonRpcRequest])

Our goals

always up-to-date, automatically generated documentation
fully support JSON-RPC 2.0 specification
express endpoint as values
ability to run it side-by-side with legacy code
integration with multiple json libraries
integration with multiple http servers

Why just not use tapir?

HTTP POST    /
{
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}

HTTP POST    /
{
   "jsonrpc":"2.0",
   "method":"sum",
   "params":[
      42,
      23
   ],
   "id":1
}

val jsonRpc = endpoint.post.in(jsonBody[JsonRpcRequest])
		.out(jsonBody[Option[JsonRpcResponse]])

Our goals

always up-to-date, automatically generated documentation
fully support JSON-RPC 2.0 specification
express endpoint as values
ability to run it side-by-side with legacy code
integration with multiple json libraries
integration with multiple http servers

Why just not use tapir?

HTTP POST    /
{
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}

HTTP POST    /
{
   "jsonrpc":"2.0",
   "method":"sum",
   "params":[
      42,
      23
   ],
   "id":1
}

Endpoint[JsonRpcRequest, JsonRpcError, Option[JsonRpcResponse]]

Our goals

always up-to-date, automatically generated documentation
fully support JSON-RPC 2.0 specification
express endpoint as values
ability to run it side-by-side with legacy code
integration with multiple json libraries
integration with multiple http servers

Why just not use tapir?

https://github.com/softwaremill/tapir/issues/621

Meet armadillo

Declarative, type-safe json-rpc endpoints library

Meet armadillo

Basic request:

--> {
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}
<-- {
   "jsonrpc":"2.0",
   "result":19,
   "id":1
}

Meet armadillo

Basic request:

--> {
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}
<-- {
   "jsonrpc":"2.0",
   "result":19,
   "id":1
}

val subtract = 
  jsonRpcEndpoint(m"subtract")

Meet armadillo

Basic request:

--> {
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}
<-- {
   "jsonrpc":"2.0",
   "result":19,
   "id":1
}

val subtract = 
  jsonRpcEndpoint(m"subtract")
  .in(
    param[Int]("subtrahend")
  )

Meet armadillo

Basic request:

--> {
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}
<-- {
   "jsonrpc":"2.0",
   "result":19,
   "id":1
}

val subtract = 
  jsonRpcEndpoint(m"subtract")
  .in(
    param[Int]("subtrahend")
      .and(param[Int]("minuend"))
  )

Meet armadillo

Basic request:

--> {
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}
<-- {
   "jsonrpc":"2.0",
   "result":19,
   "id":1
}

val subtract = 
  jsonRpcEndpoint(m"subtract")
  .in(
    param[Int]("subtrahend")
      .and(param[Int]("minuend"))
  )
  .out[Int]("result of the subtraction")

Meet armadillo

Basic request:

--> {
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}
<-- {
   "jsonrpc":"2.0",
   "result":19,
   "id":1
}

val subtract: JsonRpcEndpoint[(Int, Int), Unit, Int] = 
  jsonRpcEndpoint(m"subtract")
  .in(
    param[Int]("subtrahend")
      .and(param[Int]("minuend"))
  )
  .out[Int]("result of the subtraction")

Meet armadillo

Basic request:

--> {
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":[
      42,
      23
   ],
   "id":1
}
<-- {
   "jsonrpc":"2.0",
   "result":19,
   "id":1
}

val subtract: JsonRpcServerEndpoint[Id] = 
  jsonRpcEndpoint(m"subtract")
  .in(
    param[Int]("subtrahend")
      .and(param[Int]("minuend"))
  )
  .out[Int]("result of the subtraction")
  .serverLogic[Id] { case (subtrahend, minuend) =>
    Right(subtrahend - minuend)
  }

Meet armadillo

Request with named parameters:

--> {
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":{
      "subtrahend":23,
      "minuend":42
   },
   "id":3
}
<-- {
   "jsonrpc":"2.0",
   "result":19,
   "id":1
}

val subtract: JsonRpcServerEndpoint[Id] = 
  jsonRpcEndpoint(m"subtract")
  .in(
    param[Int]("subtrahend")
      .and(param[Int]("minuend"))
  )
  .out[Int]("result of the subtraction")
  .serverLogic[Id] { case (subtrahend, minuend) =>
    Right(subtrahend - minuend)
  }

Meet armadillo

Request with named parameters:

--> {
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":{
      "subtrahend":23,
      "minuend":42
   },
   "id":3
}
<-- {
   "jsonrpc":"2.0",
   "result":19,
   "id":1
}

val subtract: JsonRpcServerEndpoint[Id] = 
  jsonRpcEndpoint(m"subtract", ParamStructure.ByName)
  .in(
    param[Int]("subtrahend")
      .and(param[Int]("minuend"))
  )
  .out[Int]("result of the subtraction")
  .serverLogic[Id] { case (subtrahend, minuend) =>
    Right(subtrahend - minuend)
  }

Meet armadillo

Notification:

--> {
   "jsonrpc":"2.0",
   "method":"subtract",
   "params":{
      "subtrahend":23,
      "minuend":42
   }
   # no request id
}

val subtract: JsonRpcServerEndpoint[Id] = 
  jsonRpcEndpoint(m"subtract")
  .in(
    param[Int]("subtrahend")
      .and(param[Int]("minuend"))
  )
  .out[Int]("result of the subtraction")
  .serverLogic[Id] { case (subtrahend, minuend) =>
    Right(subtrahend - minuend)
  }

Meet armadillo

Batch request:

-->[
   {
      "jsonrpc":"2.0",
      "method":"subtract",
      "params":[
         42,
         23
      ],
      "id":1
   },
   {
      "jsonrpc":"2.0",
      "method":"subtract",
      "params":[
         42,
         1
      ],
      "id":2
   }
]

val subtract: JsonRpcServerEndpoint[Id] = 
  jsonRpcEndpoint(m"subtract")
  .in(
    param[Int]("subtrahend")
      .and(param[Int]("minuend"))
  )
  .out[Int]("result of the subtraction")
  .serverLogic[Id] { case (subtrahend, minuend) =>
    Right(subtrahend - minuend)
  }

<-- [
   {
      "jsonrpc":"2.0",
      "result":19,
      "id":"1"
   },
   {
      "jsonrpc":"2.0",
      "result":41,
      "id":"2"
   }
]

Interpreters - http

subtract: JsonRpcServerEndpoint[F[_]]

sum: JsonRpcServerEndpoint[F[_]]

greeting: JsonRpcServerEndpoint[F[_]]

tapir

interperter

tapirEndpoint: ServerEndpoint[-R, F[_]]

http4s

zio-http

netty

...

 Endpoint[String, (Json, StatusCode), (Option[Json], StatusCode)]

Interpreters - docs

subtract: JsonRpcServerEndpoint[F[_]]

sum: JsonRpcServerEndpoint[F[_]]

greeting: JsonRpcServerEndpoint[F[_]]

OpenRpc

interperter

openRpcSpecification: Either[Json, Yaml]

https://playground.open-rpc.org/

Interpreters

subtract: JsonRpcServerEndpoint[F[_]]

sum: JsonRpcServerEndpoint[F[_]]

greeting: JsonRpcServerEndpoint[F[_]]

Fs2

interperter

jsonRpcServer: fs2.Pipe[IO, String, Json]

unix-domain-socket

websocket

Extension points

Interceptor desing based on tapir's interceptors

Allow for customization on three different layers:

request layer
method layer
endpoint

Armadillo

jsonRpcEndpoint

Custom Interceptor

legacyEndpoint

Bonus

https://www.flaticon.com/free-icon/armadillo_4215064

Demo

Thank you!

https://github.com/input-output-hk/armadillo

https://github.com/ghostbuster91

https://github.com/softwaremill/tapir

type-safe json-rpc api

Armadillo

We are hiring :)

How it started?

JSON-RPC protocol

JSON-RPC protocol

JSON-RPC protocol

JSON-RPC protocol

JSON-RPC protocol

JSON-RPC protocol

JSON-RPC protocol

JSON-RPC protocol

JSON-RPC protocol

JSON-RPC protocol

JSON-RPC protocol

JSON-RPC protocol

JSON-RPC protocol

Our goals

Our goals

Our goals

Our goals

Our goals

Our goals

Our goals

Meet armadillo

Meet armadillo

Meet armadillo

Meet armadillo

Meet armadillo

Meet armadillo

Meet armadillo

Meet armadillo

Meet armadillo

Meet armadillo

Meet armadillo

Meet armadillo

Interpreters - http

Interpreters - docs

Interpreters

Extension points

Bonus

Demo

Thank you!

armadillo - type safe json-rpc api

More from Kasper Kondzielski