HTTP Endpoint

Dydra’s RPC service endpoint is http://api.dydra.com/rpc/2012-06-01.

The HTTP protocol version used is HTTP/1.1 as specified in RFC 2616.

HTTP Request Headers

The Host header must be present and must contain the value api.dydra.com.

The User-Agent header should be present and should contain the name and version of the client application or library issuing the request, in the commonly-used MyApp/x.y.z format.

Note

API requests that lack a proper User-Agent header may be subject to lower quality of service (for instance, stricter rate limits).

The Content-Length and Content-Type headers must be present, and must contain correct values. The value of the Content-Length header is an integer that specifies the exact octet length (that is, the byte size) of the request body. The value of the Content-Type header is an Internet media type, and varies based on the RPC protocol used; the correct values to use are described in the following subsections.

Making JSON-RPC Requests

JSON-RPC operations are performed as HTTP POST requests that use the application/json media type. They require no additional HTTP headers beyond those described in the previous subsection.

The body of the request is a JSON-encoded key-value map that must include the following keys unless otherwise specified:

Key	Value
jsonrpc	A string that specifies the JSON-RPC protocol version to use. At present, this must be specified as 2.0 to indicate the JSON-RPC 2.0 protocol. 1
id	A number or string that identifies the request. Used for batch operations (see Advanced Topics). In ordinary synchronous request-response use, you may specify null as the request identifier.
method	A case-sensitive string that specifies the name of the RPC method to invoke.
params	An array that contains the arguments (if any) to pass the RPC method. The array may be empty, in which case this key may be omitted from the request.

The request body must use the UTF-8 character encoding.

For more JSON-RPC protocol particulars, refer to the official JSON-RPC 2.0 Specification.

1

JSON-RPC 1.x is not supported by the API endpoint.

Request Example

The following is an example of invoking the DescribeService API operation using a JSON-RPC request:

POST /rpc/2012-06-01 HTTP/1.1
Host: api.dydra.com
User-Agent: MyDydraApp/1.0 (http://example.org)
Content-Type: application/json
Content-Length: ...

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "DescribeService",
  "params": []
}

Note

DescribeService is a useful API operation for basic testing, since it doesn’t specify any required parameters and requires no authentication.

Response Example

The following is an example of the response returned when invoking the DescribeService API operation using a JSON-RPC request:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: ...

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "version": "2012-06-01",
    "status": "nominal",
    "readable": true,
    "writable": true
  }
}

Making XML-RPC Requests

XML-RPC operations are performed as HTTP POST requests that use either the application/xml or text/xml media types. Both media types are equivalently supported by the Dydra API endpoint, and the server response will use the same media type as the client specified in its request.

The body of the request is an XML document with a root element of <methodCall>. The root element must be preceded by an <?xml...?> declaration that should specify the character encoding of the body. If no encoding is explicitly specified, UTF-8 is assumed.

The <methodCall> element must contain the following two elements:

Element	Value
<methodName>	A case-sensitive string that specifies the name of the RPC method to invoke.
<params>	…

For more XML-RPC protocol particulars, refer to the official XML-RPC Specification.

Request Example

The following is an example of invoking the DescribeService API operation using an XML-RPC request:

POST /rpc/2012-06-01 HTTP/1.1
Host: api.dydra.com
User-Agent: MyDydraApp/1.0 (http://example.org)
Content-Type: application/xml
Content-Length: ...

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
  <methodName>DescribeService</methodName>
  <params/>
</methodCall>

Note

DescribeService is a useful API operation for basic testing, since it doesn’t specify any required parameters and requires no authentication.

Response Example

The following is an example of the response returned when invoking the DescribeService API operation using an XML-RPC request:

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: ...

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>version</name>
            <value>
              <string>2012-06-01</string>
            </value>
          </member>
          <member>
            <name>status</name>
            <value>
              <string>nominal</string>
            </value>
          </member>
          <member>
            <name>readable</name>
            <value>
              <boolean>1</boolean>
            </value>
          </member>
          <member>
            <name>writable</name>
            <value>
              <boolean>1</boolean>
            </value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodResponse>