REST calls execute nodes
Metrici REST calls are not automatically translated to Metrici data access. Instead, calls to the REST interface are translated to an <ExecuteScript/> service call with the node passed in the nodeVersionReference parameter.
Passing parameters to REST calls
Any query parameters passed to the REST interface are passed through as request parameters.
For PUT, PATCH, or DELETE, the request body is passed to the service call as the <body> parameter.
For a POST request, if the content type indicates a form has been passed, the form parameters are converted to request parameters (using the normal conventions for HTML forms and for files when the content type is multipart/formdata). If a POST content type is not a form, the request body is passed as the <body> parameter.
The request body is not passed for a GET.
All headers are passed in a <headers> parameter as a JSON structure in which the property names are the header names converted to lower case and the property values are the header values. The authorization header is not passed.
Setting the action parameter
The <action> request parameter defaults to the HTTP method, converted to lower case. However, this can be overridden, by a query parameter of action or a form field of action. If you are passing data as a form, you must use a POST request, and if you need to perform a put or patch will need to set the action to put or patch. Remember that the action names are in lower case, unlike the HTTP methods which are in upper case.
Services may also choose to override the action by reading the action property from the request body.
Returning values from a REST service
A successful DELETE, PUT or PATCH should return a standard service response, with an errorNumber of 0.
A successful GET or POST should return an errorNumber of 0 and a response in the return element. The response is assumed to be JSON if no content-type header is set.
Setting rootPath
Any ${rootPath} sequences in the response will be replaced with the current root path variable, as for normal page output.
This default behaviour can be modified by passing a <rootPath> response element.
- Set <rootPath>false</rootPath> to turn off root path replacement.
- Set <rootPath>true</rootPath> to replace root paths (the default behaviour).
- Set <rootPath>anything else</rootPath> to change the ${rootPath} sequences to anything else.
Setting response headers
A successful call can set response headers using the headers element. This should contain headers in JSON format, e.g.
<headers>{
"content-type": "text/plain"
}</headers>Response headers are not case-sensitive.
The service should only set response headers it specifically needs, e.g. for a non-JSON content type. The underlying REST interface will handle all the standard headers.
Returning a link to a newly created node
Services that create nodes should set the <nodeVersionReference> response element to the newly created node. This will be used to create a Location header.
It would be possible to set the location header manually. However, the automated method adds root path and also makes the node version reference readily available to internal service calls.
Setting the response content type
The service can set the content type using the content-type header.
If a call returns a content type of application/xml, or if it has no content type and no <return> element, the content is assumed to be XML and the XML response document is returned. If you want to pass XML that is not a response document, return it as a string in the <return> element.
Content type modification is then applied, to prevent the rest interface being used by rogue processes to hijack the user's browser session. If the response content type indicates that HTML or XML is being returned, content will be served with a content type of text/plain. If you want to return HTML to the user, use the other features of the platform to do so.
Other content types that are not recognised are returned using the content type application/octet-stream.
Redirect
A call can set a redirect by passing back an errorNumber of 0 and passing the redirect URL in the <redirect> element.
Errors
Any errors in the calls should be returned using the standard <errorNumber> and <errorDescription> elements, and use the standard error number conventions (see Scripting errors). These will be translated to suitable HTTP status codes. The errorMessage field (used for user-friendly error messages on the user interface) is not used.
Files
Files can be retrieved using a standard GET, ensuring that the file extension is passed.
If the file extension is not passed, the call will be assumed to be a REST call.
If no file extension is present, use a query parameter of ?method=details to force return of the file.