REST Interface

REST stands for Representational State Transfer, a technique of programatically accessing a web server with defined URL patterns to retrieve information.  Designing a REST interface allows a server to provide data to client programs written in any language that can work with TCP/IP sockets, using the HTTP protocol of web servers.  Many languages have easy to use bindings to such interfaces.  There are even command line tools, such as CURL, to do so.   Much of the browser interface provided with UnForm uses REST access from Javascript to access data from the server.

UnForm's REST interface is provided in two files.  One, web/en-us/ufrest.ini, defines interfaces managed by the publisher and used by the browser interface.  This file should not be edited, and will be replaced by updates to the UnForm server.  A second file can be created, named 'ufrest.custom.ini', if you desire to create your own REST interfaces.

Interfaces

The structure of ufrest.ini is similar to an INI file.  There are sections defined with names in square brackets.  The name identifies the interface, and the URL specified by the client must include the syntax 'rest=name' in the URL structure.  Within the section are lines of code (in pure PxPlus Business Basic, with code block style block 'if ... else ... end if' in addition to native curly brace syntax) that are executed whenever that interface is executed.  The code can utilize built in objects, such as the library object, but not rule set commands or custom UnForm functions.  This code is expected to set two variables: response$ and mimetype$, to define the response data and the MIME type of that data.

The REST call from the client can specify variables in the URL, using standard HTTP query string syntax.  In addition, variables can be supplied via a POST transaction, using the standard application/x-www-form-urlencoded encoding protocol, or multipart/form-data encoding.  These variables are available to the code as cgi.name$.

A simple example that returns a string containing a URL value might look like this:

[echotest]

response$="You sent the test value "+cgi.test$

mimetype$="text/plain"

To run this interface, you would use a URL like this:

http://192.168.1.10/arc?rest=echotest&test=My%20Name

As with any HTTP-based transaction, URL values must be URL-encoded, as shown above (the %20 represents a space character).

The standard ufrest.ini file contains many examples, both simple and complex, for reference.

Authentication

REST URL calls made from Javascript in a browser-session that is already logged in will already contain a session ID header, and can operate without special authentication.  However, if you wish to access an interface outside of the bounds of a browser session, you need to provide user and password authentication.  There are two ways to do this.

If you are just doing one access, you can simply add authentication to that transaction, in the form of two URL variables:

This will create a new session for that request, and return the requested data.  Each time these variables are specified, a new session record is created.

If you will be doing multiple requests, a better method is to request an authenticated session ID and supply that with subsequent requests.  To do this, use the following URL query string:

rest=auth&userid=login&password=password

If successful, this will respond with two text lines: a session ID and the number of hours the session is valid.  On subsequent requests,you can supply this session ID as a query string variable "ufsid=sessionID".

If an error occurs, the response will begin with an ASCII NAK character (hex 15 or character 21): \x15error message, such as \x15+"Invalid password".