Protocol

This webservice uses the http protocol to submit queries to the server and to receive results. You can submit a query using an ordinary web browser and a plain old form, or you can use an http request feature of most web programming languages, or you can program a browser application (JavaScript) via XMLHttpRequest or equivalent, to submit queries in AJAX style.

Requests can be made by either POST or GET methods. If the role used requires an authcode, then the POST method must be used; for security reasons, we do not accept authcodes in urls.

XML

When retrieving data in XML form, the root element is named 'xml', and it always contains an element named 'status'. The status element has the attribute 'value' with the value 'complete', 'incomplete', or 'error'. If the value attribute is 'error', there will be a sibling element 'error' with attribute 'code'. The code attribute will have an error number, and the error body will be an error message. Both the code and the message generally originate within a subsystem such as PostgreSQL or the XML parser.

If there was no error, there will be a sibling element named 'rowcount' with the number of rows affected. If the query was a SELECT, then there will be another sibling container element 'records', with the data retrieved. See Result Formats for details on how the records are represented, because it varies from format to format.

JSON

When retrieving data in JSON form, after deserializing to an object named data, data['status'][0] will always exist and be 'complete', 'incomplete', or 'error'. If 'complete' or 'incomplete', data['rowcount'][0] will be the number of records affected. If 'error', then data['error'][0] will be the error code, and data['error'][1] will be an error message.

If there was no error, data['records'] will contain the data retrieved. See Result Formats for details on how the records are represented, because it varies from format to format.

The Error Codes page can tell you more about the types of errors, and how to research the meaning of a specific error.

Deferred Queries

If your query cannot be optimized to complete within 8 seconds, you should run it as a deferred query. A deferred query returns a status page (in XML or JSON) immediately, and runs the query in a background task allowing 10 minutes per query. If you provide a postback url as the deferred parameter, it will request that page (on your site, presumably) when it completes. The same XML or JSON page that would have been served on a regular query is provided as the body of the postback request.

Parameters

The complete list of request parameters:

JSON Request bodies

RdbHost supports JSON request bodies as an alternative to url-encoded parameters. Since JSON can nest lists and objects, the parameter format is simplified. The above listed parameters can be included as root elements of the JSON object, except that 'args' can be a simple list in lieu of 'arg000', 'arg001', etc, and named parameters can be provided as a 'namedParams' object in lieu of 'arg:name' parameters. This form is very similar to the way the JavaScript library accepts options.

Cookie Values

Cookie values can be included in the query by incorporating the cookie name like '%{cookiename}'. The value of that cookie (or '') will be safely substituted into the query.

The cookies would presumably be created by the application, in JavaScript or Python, so the cookie tokens are a convenient alternative to just using one more '%s' token.

Cookies are no longer recognized by the /db service on the server. The JavaScript library will convert any cookie tokens into regular tokens, and copy the cookie value into a regular argument, so queries using this syntax continue to work. This change improves resistance to CSRF attacks.

CGI Variables

CGI Variable values can be included in the query by incorporating the cgi-var name like '%[cgi-var]'. The value of that cgi-variable (or '') will be safely substituted into the query.

This can be useful, for example, for recording the user's IP address; the IP address is in the CGI variable 'REMOTE_ADDR', and can be included in your query like 'INSERT INTO tablename (userid, ip) VALUES(%s, %[REMOTE_ADDR])'