JSON-RPC

Last updated

JSON-RPC is a remote procedure call (RPC) protocol encoded in JSON. It is similar to the XML-RPC protocol, defining only a few data types and commands. JSON-RPC allows for notifications (data sent to the server that does not require a response) and for multiple calls to be sent to the server which may be answered asynchronously.

Contents

History

VersionDescriptionDated
1.0 Original version 2005
1.1 WD Working draft. Adds named parameters, adds specific error codes, and adds introspection functions.2006-08-07
1.1 Alt Suggestion for a simple JSON-RPC 1.1. Alternative proposal to 1.1 WD.2007-05-06
1.1 Object Specification Object Specification. Alternative proposal to 1.1 WD/1.1ALT.2007-07-30
1.2 Proposal. A later revision of this document was renamed to 2.0.2007-12-27
2.0 Specification proposal 2009-05-24
2.0 (Revised-) Specification 2010-03-26

Usage

JSON-RPC works by sending a request to a server implementing this protocol. The client in that case is typically software intending to call a single method of a remote system. Multiple input parameters can be passed to the remote method as an array or object, whereas the method itself can return multiple output data as well. (This depends on the implemented version.)

All transfer types are single objects, serialized using JSON. [1] A request is a call to a specific method provided by a remote system. It can contain three members:

The receiver of the request must reply with a valid response to all received requests. A response can contain the members mentioned below.

Since there are situations where no response is needed or even desired, notifications were introduced. A notification is similar to a request except for the id, which is not needed because no response will be returned. In this case the id property should be omitted (Version 2.0) or be null (Version 1.0).

Examples

In these examples, --> denotes data sent to a service (request), while <-- denotes data coming from a service. Although <-- is often called a response in client–server computing, depending on the JSON-RPC version it does not necessarily imply an answer to a request.

Version 2.0

Request and response:

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

Notification (no response):

-->{"jsonrpc":"2.0","method":"update","params":[1,2,3,4,5]}

Version 1.1 (Working Draft)

Request and response:

-->{"version":"1.1","method":"confirmFruitPurchase","params":[["apple","orange","mangoes"],1.123],"id":"194521489"}<--{"version":"1.1","result":"done","error":null,"id":"194521489"}

Version 1.0

Request and response:

-->{"method":"echo","params":["Hello JSON-RPC"],"id":1}<--{"result":"Hello JSON-RPC","error":null,"id":1}

See also

Related Research Articles

The Lightweight Directory Access Protocol is an open, vendor-neutral, industry standard application protocol for accessing and maintaining distributed directory information services over an Internet Protocol (IP) network. Directory services play an important role in developing intranet and Internet applications by allowing the sharing of information about users, systems, networks, services, and applications throughout the network. As examples, directory services may provide any organized set of records, often with a hierarchical structure, such as a corporate email directory. Similarly, a telephone directory is a list of subscribers with an address and a phone number.

In distributed computing, a remote procedure call (RPC) is when a computer program causes a procedure (subroutine) to execute in a different address space, which is written as if it were a normal (local) procedure call, without the programmer explicitly writing the details for the remote interaction. That is, the programmer writes essentially the same code whether the subroutine is local to the executing program, or remote. This is a form of client–server interaction, typically implemented via a request–response message-passing system. In the object-oriented programming paradigm, RPCs are represented by remote method invocation (RMI). The RPC model implies a level of location transparency, namely that calling procedures are largely the same whether they are local or remote, but usually, they are not identical, so local calls can be distinguished from remote calls. Remote calls are usually orders of magnitude slower and less reliable than local calls, so distinguishing them is important.

Short Message Peer-to-Peer (SMPP) in the telecommunications industry is an open, industry standard protocol designed to provide a flexible data communication interface for the transfer of short message data between External Short Messaging Entities (ESMEs), Routing Entities (REs) and SMSC.

XML-RPC is a remote procedure call (RPC) protocol which uses XML to encode its calls and HTTP as a transport mechanism.

SOCKS is an Internet protocol that exchanges network packets between a client and server through a proxy server. SOCKS5 optionally provides authentication so only authorized users may access a server. Practically, a SOCKS server proxies TCP connections to an arbitrary IP address, and provides a means for UDP packets to be forwarded.

Modbus or MODBUS is a client/server data communications protocol in the application layer of the OSI model. It was originally published by Modicon in 1979 for use with its programmable logic controllers (PLCs). Modbus has become a de facto standard communication protocol for communication between industrial electronic devices in a wide range of buses and network.

<span class="mw-page-title-main">JSON</span> Open standard file format and data interchange

JSON is an open standard file format and data interchange format that uses human-readable text to store and transmit data objects consisting of attribute–value pairs and arrays. It is a common data format with diverse uses in electronic data interchange, including that of web applications with servers.

<span class="mw-page-title-main">XMLHttpRequest</span> Web API to transfer data between a web browser and a web server

XMLHttpRequest (XHR) is a JavaScript class containing methods to asynchronously transmit HTTP requests from a web browser to a web server. The methods allow a browser-based application to make a fine-grained server call and store the results in XMLHttpRequest's responseText attribute. The XMLHttpRequest class is a component of Ajax programming. Prior to Ajax, an HTML form needed to be completely sent to the server followed by a complete browser page refresh.

The Simple Common Gateway Interface (SCGI) is a protocol for applications to interface with HTTP servers, as an alternative to the CGI protocol. It is similar to FastCGI but is designed to be easier to parse. Unlike CGI, it permits a long-running service process to continue serving requests, thus avoiding delays in responding to requests due to setup overhead.

XML Interface for Network Services (XINS) is an open-source technology for definition and implementation of internet applications, which enforces a specification-oriented approach.

Real-Time Messaging Protocol (RTMP) is a communication protocol for streaming audio, video, and data over the Internet. Originally developed as a proprietary protocol by Macromedia for streaming between Flash Player and the Flash Communication Server, Adobe has released an incomplete version of the specification of the protocol for public use.

<span class="mw-page-title-main">NETCONF</span> Network management protocol

The Network Configuration Protocol (NETCONF) is a network management protocol developed and standardized by the IETF. It was developed in the NETCONF working group and published in December 2006 as RFC 4741 and later revised in June 2011 and published as RFC 6241. The NETCONF protocol specification is an Internet Standards Track document.

CANopen is a communication protocol and device profile specification for embedded systems used in automation. In terms of the OSI model, CANopen implements the layers above and including the network layer. The CANopen standard consists of an addressing scheme, several small communication protocols and an application layer defined by a device profile. The communication protocols have support for network management, device monitoring and communication between nodes, including a simple transport layer for message segmentation/desegmentation. The lower level protocol implementing the data link and physical layers is usually Controller Area Network (CAN), although devices using some other means of communication can also implement the CANopen device profile.

The Web Application Description Language (WADL) is a machine-readable XML description of HTTP-based web services. WADL models the resources provided by a service and the relationships between them. WADL is intended to simplify the reuse of web services that are based on the existing HTTP architecture of the Web. It is platform and language independent and aims to promote reuse of applications beyond the basic use in a web browser. WADL was submitted to the World Wide Web Consortium by Sun Microsystems on 31 August 2009, but the consortium has no current plans to standardize it. WADL is the REST equivalent of SOAP's Web Services Description Language (WSDL), which can also be used to describe REST web services.

Action Message Format (AMF) is a binary format used to serialize object graphs such as ActionScript objects and XML, or send messages between an Adobe Flash client and a remote service, usually a Flash Media Server or third party alternatives. The Actionscript 3 language provides classes for encoding and decoding from the AMF format.

<span class="mw-page-title-main">Key Management Interoperability Protocol</span> Communication protocol for the manipulation of cryptographic keys

The Key Management Interoperability Protocol (KMIP) is an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server. This facilitates data encryption by simplifying encryption key management. Keys may be created on a server and then retrieved, possibly wrapped by other keys. Both symmetric and asymmetric keys are supported, including the ability to sign certificates. KMIP also allows for clients to ask a server to encrypt or decrypt data, without needing direct access to the key.

JSON-WSP is a web service protocol that uses JSON for service description, requests and responses. It is inspired from JSON-RPC, but the lack of a service description specification with documentation in JSON-RPC sparked the design of JSON-WSP.

<span class="mw-page-title-main">Json2Ldap</span>

Json2Ldap is a JSON-to-LDAP gateway software, written in Java and developed by Nimbus Directory Services. It provides a JSON-RPC 2.0 interface for web clients to access one or more LDAP v3 - compatible directories. The Json2Ldap web API supports the standard LDAP directory requests as well as several extended operations and controls.

The RESTful Service Description Language (RSDL) is a machine- and human-readable XML description of HTTP-based web applications.

The Language Server Protocol (LSP) is an open, JSON-RPC-based protocol for use between source code editors or integrated development environments (IDEs) and servers that provide "language intelligence tools": programming language-specific features like code completion, syntax highlighting and marking of warnings and errors, as well as refactoring routines. The goal of the protocol is to allow programming language support to be implemented and distributed independently of any given editor or IDE. In the early 2020s LSP quickly became a "norm" for language intelligence tools providers.

References

  1. "specification - JSON-RPC - Trac". Archived from the original on 2008-05-17. Retrieved 2008-05-14.
  2. "JSON-RPC 2.0 Specification". id: An identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification. The value SHOULD normally not be Null and Numbers SHOULD NOT contain fractional parts
  3. "JSON-RPC 2.0 Specification". A Notification is a Request object without an "id" member. A Request object that is a Notification signifies the Client's lack of interest in the corresponding Response object, and as such no Response object needs to be returned to the client. The Server MUST NOT reply to a Notification, including those that are within a batch request. Notifications are not confirmable by definition, since they do not have a Response object to be returned. As such, the Client would not be aware of any errors (like e.g. "Invalid params","Internal error").
  4. "JSON-RPC 2.0 Specification". result: This member is REQUIRED on success. This member MUST NOT exist if there was an error invoking the method. The value of this member is determined by the method invoked on the Server.
  5. "JSON-RPC 2.0 Specification". error: This member is REQUIRED on error. This member MUST NOT exist if there was no error triggered during invocation. The value for this member MUST be an Object as defined in section 5.1.
  6. "JSON-RPC 2.0 Specification". Error object: When a rpc call encounters an error, the Response Object MUST contain the error member with a value that is a Object with the following members: (code) - A Number that indicates the error type that occurred. This MUST be an integer. (message) - A String providing a short description of the error. The message SHOULD be limited to a concise single sentence. (data) - A Primitive or Structured value that contains additional information about the error. This may be omitted. The value of this member is defined by the Server (e.g. detailed error information, nested errors etc.).