JSON-RPC Protocol Converter API Reference

Technical documentation for developers integrating protocol conversion capabilities into their applications

On this page

Need to convert protocols?

Try our interactive converter tool for quick protocol conversion.

Try Converter Tool

Overview

The JSON-RPC Protocol Converter API allows developers to convert between JSON-RPC and other API protocols, such as REST and GraphQL. This makes it easier to integrate JSON-RPC into systems that use different API paradigms or to migrate between protocol styles while maintaining compatibility.

This API is designed to work in both browser and Node.js environments, making it versatile for various use cases including API gateways, proxies, and development tooling.

Installation

The Protocol Converter API can be installed via npm:

npm install @jsonrpc-tools/converter

Or included via CDN:

<script src="https://cdn.jsonrpc.dev/converter/v1/converter.min.js"></script>

API Reference

Core Methods

convertJsonRpcToRest(jsonRpcRequest, options)

Converts a JSON-RPC request to a REST API request format.

Parameters:

  • jsonRpcRequest (Object): The JSON-RPC request object
  • options (Object, optional): Conversion options

Returns:

A REST API request object with method, path, and body properties

convertRestToJsonRpc(restRequest, options)

Converts a REST API request to a JSON-RPC request format.

Parameters:

  • restRequest (Object): The REST request object
  • options (Object, optional): Conversion options

Returns:

A valid JSON-RPC request object

convertJsonRpcToGraphQL(jsonRpcRequest, options)

Converts a JSON-RPC request to a GraphQL query.

Parameters:

  • jsonRpcRequest (Object): The JSON-RPC request object
  • options (Object, optional): Conversion options

Returns:

A GraphQL query string or document object

REST Conversion

Mapping Convention

When converting between JSON-RPC and REST, the following mapping convention is used:

JSON-RPC to REST Mapping
JSON-RPC ElementREST Element
Method nameURL path and HTTP method
Named parameters (object)Query parameters and/or request body
Positional parameters (array)URL path segments and/or request body
IDCustom header (X-Request-ID)

Example Conversions:

JSON-RPC Request
{
  "jsonrpc": "2.0",
  "method": "user.get",
  "params": {"id": 123},
  "id": 1
}
REST Request
{
  "method": "GET",
  "path": "/user/123",
  "headers": {
    "X-Request-ID": "1"
  }
}

GraphQL Conversion

Mapping Convention

When converting between JSON-RPC and GraphQL, the following mapping convention is used:

JSON-RPC to GraphQL Mapping
JSON-RPC ElementGraphQL Element
Method nameQuery or mutation name
ParametersQuery variables
IDOperation name

Example Conversions:

JSON-RPC Request
{
  "jsonrpc": "2.0",
  "method": "user.get",
  "params": {"id": 123},
  "id": 1
}
GraphQL Query
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

variables: { "id": 123 }

Conversion Options

The converter API supports various options to customize the conversion process:

REST Conversion Options
OptionDescriptionDefault
methodMappingCustom mapping of JSON-RPC methods to REST endpoints{}
baseUrlBase URL prefix for REST endpoints""
useQueryParamsWhether to use query parameters for GET requeststrue
GraphQL Conversion Options
OptionDescriptionDefault
outputFormatOutput as 'string' or 'document'"string"
typeMapMapping of parameter names to GraphQL types{}
defaultReturnFieldsFields to include in the response when not specified[]

Usage Examples

Converting JSON-RPC to REST

import { convertJsonRpcToRest } from '@jsonrpc-tools/converter';

const jsonRpcRequest = {
  jsonrpc: "2.0",
  method: "user.get",
  params: { id: 123 },
  id: 1
};

const restRequest = convertJsonRpcToRest(jsonRpcRequest, {
  baseUrl: '/api'
});

console.log(restRequest);
// Output:
// {
//   method: "GET",
//   path: "/api/user/123",
//   headers: { "X-Request-ID": "1" }
// }

Converting REST to JSON-RPC

import { convertRestToJsonRpc } from '@jsonrpc-tools/converter';

const restRequest = {
  method: "POST",
  path: "/api/users",
  body: {
    name: "John Doe",
    email: "[email protected]"
  },
  headers: {
    "X-Request-ID": "abc123"
  }
};

const jsonRpcRequest = convertRestToJsonRpc(restRequest);

console.log(jsonRpcRequest);
// Output:
// {
//   jsonrpc: "2.0",
//   method: "users.create",
//   params: {
//     name: "John Doe",
//     email: "[email protected]"
//   },
//   id: "abc123"
// }

Converting JSON-RPC to GraphQL

import { convertJsonRpcToGraphQL } from '@jsonrpc-tools/converter';

const jsonRpcRequest = {
  jsonrpc: "2.0",
  method: "user.update",
  params: {
    id: 123,
    name: "Jane Doe"
  },
  id: 1
};

const graphqlQuery = convertJsonRpcToGraphQL(jsonRpcRequest, {
  defaultReturnFields: ["id", "name", "updatedAt"]
});

console.log(graphqlQuery);
// Output:
// mutation UpdateUser($id: ID!, $name: String!) {
//   updateUser(id: $id, name: $name) {
//     id
//     name
//     updatedAt
//   }
// }