Red Stag Fulfillment exposes all of it’s API endpoints via HTTP using the JSONRPC protocol. This page explains the general method of authenticating and calling methods. Each method is documented in detail in the Reference section.

There are only two actual JSONRPC methods: login and call. The login procedure returns a session ID which is then passed to subsequent requests to call. The call procedure takes the API method name and other request parameters.

Request Format

All requests must be POST requests with the request parameters given as a JSON-encoded string in the POST body. The request parameters are as follows:

jsonrpc
The JSONRPC protocol version number. Must be "2.0".
id
A unique identifier for the request that will be included in the response.
method
The remote procedure to call. This should always be either `login` or `call`.
params
An array of request parameters specific to the remote procedure being called (see below for details).

Response Format

The response will be a JSON-encoded string with the following properties:

jsonrpc
The JSONRPC protocol version number ("2.0").
id
The unique identifier that matches the id given in the request.
error
If there is an error, this will be an object with keys `code` and `message`. See "Error Codes" for a list of general error codes.
result
If an error did not occur this will contain the appropriate response data, otherwise this will be empty.

Error Codes

code message meaning
-32700 Parse error Invalid JSON was received by the server.
An error occurred on the server while parsing the JSON text.
-32600 Invalid Request The JSON sent is not a valid Request object.
-32601 Method not found The method does not exist / is not available.
-32602 Invalid params Invalid method parameter(s).
-32603 Internal error Internal JSON-RPC error.

The error codes are easier to read if you first multiply by -1 and then subtract 32000. From this point forward, all error codes mentioned will have this formula already applied to them, but due to the requirement of hte JSONRPC protocol, they will be reported via the API without the formula applied.

login (username, api_key)

An API session is started by calling the login method to get a session ID. The session ID must be provided for subsequent calls to call and will expire after 24 hours.

Parameters

order description
0 The API user’s username.
1 The API user’s API key (password).

Return Value

Upon a successful login the result will be a session ID which is a 32-character hexadecimal string.


Example Request

POST/backend/api/jsonrpc
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "login",
    "params" : [
        "username",
        "password"
    ]
}

Example Response

An example response for a successful login:

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "result" : "be1c13ed4e03f0ed7f1e4053dfff9658"
}

An example response for if the session is expired:

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : {
        "code" : -32005,
        "message" : "Session expired. Try to relogin."
    }
}

Error Codes

code message
2 Access denied.
6 Required parameter is missing, for more details see “exception.log”.

call (session_id, method, arguments)

The ‘call’ method is used to call all other API endpoints which are detail in the pages under the “API Reference” heading in the sidebar.

Parameters

order description
0 The session id.
1 The API method to call. This always takes the form of “resource.method”. E.g. “state.get
2 The arguments to the API method. If there are no additional arguments this parameter may be omitted.

Return Value

The response may be any valid JSON type according to the method which was called.


Error Codes

code message
2 Access denied.
3 Invalid api path.
4 Resource path is not callable.
5 Session expired. Try to relogin.
? Other error codes may be used depending on which method was called.