REST Support

9.9A

The PWS Server has been modified to provide a WEB API interface based on the REST (Representational State Transfer) technology. The REST in the PWS Server provides PLB Web Developers with the framework, infrastructure, and PLB language constructs to implement Web REST APIs accessible from any Web application. The RESTful Web Services provides an interface that is lightweight, maintainable, and scalable that gives the PLB Web Developer a design environment with access to the PLBWIN, PLBNET, and PLB (Linux) runtimes to execute PL/B programs. For more information and tutorials on the REST technology, see the following links:

https://en.wikipedia.org/wiki/Representational_state_transfer

This link provides a good overview of the RESTful Web Services concept\technology. This is a good starting point for the PL/B Web Developer that has an interest in proving a REST Web Service using the PL/B Web Server.

http://www.restapitutorial.com/

This link gives a tutorial perspective on 'What is REST?'. This tutorial gives information that can help reinforce expected standards and rules required a REST Web Service.

OVERVIEW (PL/B REST Support)

What is REST?

• Representational state transfer (REST) or RESTful web services are one way of providing interoperability between a PL/B Web Server (PWS) and generic web clients.
   

• In a REST web service, requests made to a resource's URL will elicit a response that may be in XML, HTML, JSON.
   

• The PWS Server can be configured to detect a specific base URL and execute a PL/B program using a PLBWIN, PLBNET, or PLB (Linux) runtime. This program uses the RUNTIME object 'CgiString' method operations to obtain information about a request. The program can return the response to a web client using the RUNTIME object 'HttpResponse' method or using the PL/B STREAM instruction.

• If the PL/B program is terminated without giving a response, a default HTTP response with an HTTP status code of 500 (internal error) is returned to the web client.

REST Reference Web Sites for information on REST services.

https://en.wikipedia.org/wiki/Representational_state_transfer

http://www.restapitutorial.com/

REST Sample Code and Test Tools

Phonemsg.pls Sample Program

A sample program named 'phonemsg.pls' is available in your PWS programs directory. When the PWS server is configured to provide the PL/B REST 'MyServices/' service, the PWS executes the 'phonemsg.plc' program when the input url from a web client specifies the segments as 'MyServices/phonemsg'.

 

PLBWIN INI Configuration Keyword:

 

PLB_CGI_DIR=c:\mypath\mycgi\z

 

PLBWEBSRV INI Configuration Minimum Keywords:

 

PLBWEB_CGI_INFODIR=c:\mypath\mycgi\z

PLBWEB_REST_BASEURL01=MyServices/

PLBWEB_REST_CMDLINE01=plbwin.exe -h %s %s

 

Restcli Html Web Pages created using Dreamweaver Project

Sample HTML web pages have been generated using the Dreamweaver Project which can access a PWS server configured to support the PL/B RESET 'MyServices/' service. These HTML pages utilize JavaScript functions which interface with the PWS REST service. The sample HTML, JavaScript, and CSS files are provided as follows:

restsupp.css

restsupp.js

restentry.html

restmain.html

restquery.html

Note: The end-user must modify the 'restsupp.js' file variable named 'commAddr' to provide the URL\IP address and port of the PWS server being accessed.

var commAddr = "http://192.168.1.12:8081/MyServices/phonemsg";

Chrome

The Chrome browser and the ARC (Advanced Rest Client) App can be used in the evaluation and testing of a REST service implemented by a PL/B developer.

 

PL/B Web Server Configuration Keywords

The PL/B REST support allows up to ninty-nine (99) REST web services to be configured using the PWS keywords as follows:

PL/B Web Server CGI Information Generation

The PLBWEB_CGI_INFODIR configuration keyword specifies the location of the temporary CGI files. These temporary CGI files are created by the PWS REST services when a web client REST request is accepted. These temporary CGI files are loaded into memory by the PL/B runtime specified in the 'PLBWEB_REST_CMDLINE<nn>' keyword configured for the REST service specified in the base URL. After a temporary CGI file is loaded by the PL/B runtime, it is immediately deleted before the REST PL/B program starts executing.

The RESET PL/B program can use the RUNTIME 'CgiString' method to access the CGI data fields as needed to process the REST API request. The following keywords are an example of the CGI fields available to the REST PL/B program:

GATEWAY_INTERFACE=CGI/1.1

AUTH_TYPE=None

CONTENT_LENGTH=53

REMOTE_ADDR=192.168.1.12

REQUEST_METHOD=PUT

REQUEST_URI=/MyServices/phonemsg/6

SCRIPT_NAME=/MyServices/phonemsg/6

SERVER_SOFTWARE=PlbWebSrv

PROTOCOL=HTTP/1.1

SERVER_PORT=8081

HTTP_HOST=192.168.1.12:8081

Note:

1.   If CGI 'AUTH_TYPE' field is returned as 'Basic', then extra CGI keywords are available as follows:

AUTH_USER=Bill

REMOTE_USER=Bill

AUTH_DATA=<base64 username:password string>

PL/B Language REST Support

1.   The PL/B runtimes including 'plb' (Linux\Linux), 'plbwin', and 'plbnet' support a new command line option named '-cgi <filename>'. The 'cgi' runtime option is ONLY generated by a PWS server configured to support REST services. When the 'cgi' option is detected by the runtime, it causes the runtime to load the <filename> temporary CGI file and allows the RUNTIME 'CgiString' to access the REST CGI keyword fields. After the <filename> CGI data is loaded, the runtime deletes the temporary CGI file before the REST PL/B program starts executing.

2.   The 'PLB_CGI_DIR=' keyword MUST be specified in the runtime INI [Environment] section and the assigned keyword string must match the 'PLBWEB_CGI_INFODIR' keyword string specified in the PWS INI file.

3.   The PL/B XDATA data object can be used to create and decode JSON and XML data processed by the REST request and result strings.

4.   Optionally, the PL/B STREAM instruction using *STDIN and *STDOUT can get\send a HTTP POST, PUT, DELETE, and PATCH request.

Note:

• The 'STREAM *STDOUT' allows the PL/B REST program to send customized data to the REST client application.

• When the PL/B REST program uses the 'STREAM *STDOUT' to output customized data, the RUNTIME 'HttpResponse' method MUST NOT be used. Otherwise, unexpected\indeterminate results can occur.

 

5.   RUNTIME Object Method Changes for PL/B Runtimes

The RUNTIME object for the PL/B runtimes 'plb', 'plbwin', and 'plbnet' (excluding PWS) has been modified to support the 'CgiString' and 'HttpResponse' methods as follows:

'CgiString' REST API Support

The RUNTIME 'CgiString' method accesses HTTP header fields that are submitted by a REST API.

Note the following:

A. When a REST API request is accepted by a PWS server, the PWS server extracts the Http header data from the request and stores it into a CGI data file. In this case, the PWS server stores the CGI data into a file based on the PWS keyword named 'PLBWEB_CGI_INFODIR'. Also, the PWS server starts a PL/B runtime including the command line option '-cgi <filename>'.

B. When the PL/B runtime detects the new command line option named '-cgi <filename>', the PL/B runtime preloads the <filename> data so the RUNTIME object 'CgiString' can access the CGI keyword data. The CGI keywords are the same as described for the 'CgiString' for a PWS server program. After the <filename> data is preloaded, the PL/B runtime deletes the temporary CGI file before the PL/B REST program starts executing.

C. Also, if CGI 'AUTH_TYPE' keyword has a returned string value of 'Basic', these CGI keywords are available with meaningful data:

AUTH_USER

REMOTE_USER

AUTH_DATA

'HttpResponse' REST API Support

The RUNTIME object method named 'HttpResponse' is available to return the results of a REST API operation to the client browser that submitted the REST request.

 

This method generates a HTTP response in HTTP 1.1 format. See the RUNTIME 'HttpResponse' method description found in the PL/B Language Reference manual for more details. The generated HTTP response includes the following header fields:

 

1) The HTTP 1.1 header is generated.

"HTTP/1.1 {httpcode} <pre-defined string>\015\012"

The {httpcode} value is specified by the RUNTIME 'HttpResponse' method.

The <pre-defined string> is the expected text string associated with the {httpcode} value as follows:

If the {httpcode} value is not one of the values in this table, then the default result will be a code of '500' with a text string of 'Internal Server Error' with a mime type of 'text/plain' and there is no body in the HTTP response message.

2) The connection header field is added as follows:

"Connection: close\015\012"

3) By default, this header field is added to the response output unless the 'HttpResponse' {options} bit mask specifies the '0x0002' (Allow Cache Control).

"Cache-Control: no-cache,no-store\015\012"

The {options} '$HttpResp_AllowCacheControl' (0x0002) bitmask value exclude the output of this header field.

4) The content type header field is added as:

"Content-Type: {mimetype>}\015\012"

The {mimetype} value is specified by the RUNTIME 'HttpResponse' method.

5) By default 'Access-Control-Allow' HTTP headers are added to the response shown as follows:

"Access-Control-Allow-Credentials: true\015\012"

"Access-Control-Allow-Origin: *\015\012"

"Access-Control-Allow-Headers: Content-Type\015\012"

"Access-Control-Allow-Methods: POST, GET, OPTIONS, DELETE, PATCH, PUT\015\012"

The {options} '$HttpResp_NoAccessControl' (0x0001) bitmask value excludes the output of these header fields.

6) All extra headers specified by the HttpResponse {extrahdrs} parameter are added at this point.

7) The content length is calculated for the {body} and added to the HTTP response message as follows:

"Content-Length: nnnnn\015\012"

8) The HTTP 'end of header' "\015\012" is placed in the HTTP response message.

9) If the {body} content length is non-zero, the {body} data is added to the HTTP response exactly as provided by the user program.