5.2 API publication

Each API stores a script, parameter examples and execution options. After publication, clients use its defined HTTP method and path.

Guide

• Script support: write DataQL and SQL, combine queries and transform results.
• Request parameters: read URL parameters, JSON, forms, uploads, headers and cookies.
• API responses: return JSON, errors, binary data or custom HTTP responses.
• API options: configure parameter wrapping, structured responses and response templates.
• Java invocation: call published, enabled APIs by path or ID through ApiService.

Invocation example

These examples call a published POST /hello whose script is return {"message": ${message}};. The default URL is /api/hello; see Entry configuration for prefixes.

Callers supply application credentials with API access permission. The following uses the example application's cookie login:

curl

Log in and invoke

# Log in to the example application and save its cookie.
curl -c cookies.txt -X POST http://127.0.0.1:8080/session/login \
  -d 'username=api&password=example-password'

# Call the published API.
curl -b cookies.txt http://127.0.0.1:8080/api/hello \
  -H 'Content-Type: application/json' \
  -d '{"message":"Hello Dataway"}'

JavaScript

Call from an authenticated same-origin page

const response = await fetch('/api/hello', {
    method: 'POST',
    credentials: 'same-origin',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({message: 'Hello Dataway'})
});
if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
}
const result = await response.json();
if (!result.success) {
    throw new Error(result.message);
}
console.log(result.value);

The default response template produces a response such as:

Example response

{
  "success": true,
  "message": "OK",
  "code": 0,
  "lifeCycleTime": 2,
  "executionTime": 1,
  "value": {"message": "Hello Dataway"}
}

Check the HTTP status, then read success for execution status and value for business data. The JavaScript example prints {"message":"Hello Dataway"}. Follow the API contract when using a custom template or disabling Structure; see API responses.

Routes match both method and path. GET and POST can address separate APIs. Define HEAD explicitly; its response contains headers only. See Request parameters for request formats.

Use the external URL when a reverse proxy is involved. The host application configures CORS, login, CSRF and request size limits.