|Top Previous Next|
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.
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:
response$="You sent the test value "+cgi.test$
To run this interface, you would use a URL like this:
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.
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:
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".