Protocol Request

Action

An action is a unit of work that the client can request the server to perform. Action has a name which uniquely identify an action to be carried out.

Action Name

Action name consists of two parts, a namespace and a method, which are joined together using a colon (:). An example of the canonical way to represent an action name is record:fetch, in which record is the namespace and fetch is the method.

• namespace

  The action namespace is a name of a group of related actions. This also serves as a namespace to differentiate actions which might have the same name.

  The action namespace is the same as the first part (before colon) of an action name.

• method

  This identify the actual method being requested by the client.

  The action method is the same as the second part (after colon) of an action name.

URL

URL-based routing

URL: /<version>/<namespace>/<method>

• version

  Version number in the URL is used to route the request to different version of the API, which might co-exists with other version. This allows the API to continue evolving in a backward-incompatible manner while also allowing older clients to continue functioning using an older API.

  Example of version: v1, v1.1, v2 etc.

• namespace

  Namespace of the requested action.

  For action without a namespace (such as :batch), this part is omitted from the URL.

• method

  Method of the requested action in the specified namespace.

Example

• /v1/record/fetch

Parameter-based routing

URL: /<version>

Instead of specifying the action in the URL, it is possible to specify the action as a parameter.

Discussions

One of the following format for parameter-based routing:

• In query string: ?action=record:fetch

• In header: X-Ourd-Action: record:fetch

• In request body: {"action": "record:fetch"}

Response Format

(This is a stub.)

Parameters:

• request_id (string)

  Request identifier.

  This string is generated by the server to uniquely identify a request. This is sent to client for diagnostic purpose.

• error (dict, optional)

  Error payload if and only if an error occurred. (See Error)

Error

This section describes how the server signal to the client that an error occurred.

HTTP Status

When an action is executed, the server should return the HTTP status code 200 OK. This means that both the client and server understands the request, and the action executed in an expected manner, regardless of whether the action executed completely or partially. As an example, for a record:fetch action, even if the requested record does not exists, the action is executed without an unexpected error.

If the request is unexpected or if the server encountered an error while handling a request, the server should return a 4XX code for client-side error, or a 5XX code for server-side error. The exact code to be used should conform to RFC 2616.

Error Payload

Whenever possible, the server should return an error payload in JSON stating the error. However, the client should not expect that the response content to be always a JSON-formatted payload. In this case, the client must rely on the HTTP status code to handle the error gracefully.

This error format applies to all request actions. For actions that can be executed partially, the action documentation should define how the partial error is returned to client.

Parameters

• message (string)

  Detailed description of the error.

  The message describes the error occurred, an optionally suggest ways to mitigate the error. This message is not localized and should not be displayed to the user.

• type (string)

  Type of the error.

  This is how the client tells which part of the system generated the error.

• code (integer)

  The error code.

  The error code is specific to the type of the error and uniquely identify a specific error that occurred within the scope of type. This is also the programmatic way to identify the error and affect how the error will be handled. If the client intend to show information about the error to the user, the client should display a localized string depending on this code as well as the type of the error.

• info (dict, optional)

  Additional information about the error.

  The server may return additional information about the error such as the required parameter names missing in the request. The format of this dict is defined by the action documentation and depends on type and code of the error.

  This is helpful in programatically handling the request and also building localized string that will be displayed to the user.

Examples

{
    "request_id": "REQUEST_ID",
    "error": {
        "message": "The required parameter `ids` is missing.",
        "type": "FetchRecordsRequestError",
        "code": 100,
        "info": {
            "parameter": "ids"
        }
    }
}

Discussion

• If the request format accepts a locale parameter, we should be able to build localized error message that is suitable to be displayed to the user. This helps the app-developer/API-developer so that they don't need to build localized string for each error code. Facebook Graph API does the same thing. (see https://developers.facebook.com/docs/graph-api/using-graph-api/v2.2).

  If we do this, the localized error message can be put in the info dict, or we can add localized_message in the top level of the error payload.