Skip to end of metadata
Go to start of metadata

To connect to a RESTful Web Service Provider, first create a new RESTful Configuration in the Project Browser of the Ignition Designer by right­-clicking on RESTful Configurations in the Web Services section and selecting New RESTful Configurations


Watch the Video





General Settings


NameDescription

URL

The target location URL for the RESTful configuration. 

Example: https://reqres.in/api/users

HTTP method

HTTP requests include a method, which is a keyword explaining the action that the client wants the server to perform for the material included in the request. The available HTTP methods are GETPOSTPUTDELETE

See Web Services Overview - HTTP for more information.

Data format

The available options are JSON and XML.

Encoding

The available encoding types are UTF_8, UTF_16, ISO_8859_1, Windows_1252, and ASCII.
Query Spaces

Drop-down list that determines whether "+" or "%20" is used as the escape character(s) for typed spaces in the URL Query String. Default is "Plus (+)".


Example:

Plus (+): http://localhost:8088/main/system/ws/rest/test?test=string+with+spaces
Percent (%20): http://localhost:8088/main/system/ws/rest/test?test=string%20with%20spaces

Timeout

This is the time the module will wait until a response is received from the URL. If no response is received then an error is generated.

Calls that take more than < Gateway Read Timeout Setting> seconds will time out in the Client.

Max retries

The maximum number of retries, in case of connection failure. Default value is 3.

Bypass SSL server authentication

The consumer (client) will bypass SSL server authentication if the checkbox is selected.

Enable error reporting for failure HTTP response codes 

An exception will be thrown when the web service call results in a code like 404 or other error codes, if the checkbox is selected.




HTTP Authentication

NameDescription

Type

The options are HTTP Basic, HTTP Digest, and HTTP NTLM.

Username

The user name to set for the new RESTful configuration.

Password

The password to set for the new RESTful configuration.




Request Message


NameDescription

Request Header

Depending on the Web Service, these can be used to identify the format of the body object you are POSTing to the web service, or perhaps an API key or other identifying tool. A standard Request Header Item would be Content-type which can be used to indicate the format of the body object. The most common value for Content-type is application/json, but this is entirely dependent upon the web service you are posting to and the data format you are posting.

# Data interchange
application/atom+xml atom;
application/json json map topojson;
application/ld+json jsonld;
application/rss+xml rss;
application/vnd.geo+json geojson;
application/xml rdf xml;

# JavaScript
application/javascript js;

# Manifest files
application/manifest+json webmanifest;
application/x-web-app-manifest+json webapp;
text/cache-manifest appcache;

# Media files
audio/midi mid midi kar;
audio/mp4 aac f4a f4b m4a;
audio/mpeg mp3;
audio/ogg oga ogg opus;
audio/x-realaudio ra;
audio/x-wav wav;
image/bmp bmp;
image/gif gif;
image/jpeg jpeg jpg;
image/jxr jxr hdp wdp;
image/png png;
image/svg+xml svg svgz;
image/tiff tif tiff;
image/vnd.wap.wbmp wbmp;
image/webp webp;
image/x-jng jng;
video/3gpp 3gp 3gpp;
video/mp4 f4p f4v m4v mp4;
video/mpeg mpeg mpg;
video/ogg ogv;
video/quicktime mov;
video/webm webm;
video/x-flv flv;
video/x-mng mng;
video/x-ms-asf asf asx;
video/x-ms-wmv wmv;
video/x-msvideo avi;
image/x-icon cur ico;

# Microsoft Office
application/msword doc;
application/vnd.ms-excel xls;
application/vnd.ms-powerpoint ppt;
application/vnd.openxmlformats-officedocument.wordprocessingml.document docx;             
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet xlsx;
application/vnd.openxmlformats-officedocument.presentationml.presentation pptx;

# Web fonts
application/font-woff woff;
application/font-woff2 woff2;
application/vnd.ms-fontobject eot;
application/x-font-ttf ttc ttf;
font/opentype otf;

# Other
application/java-archive ear jar war;
application/mac-binhex40 hqx;
application/octet-stream bin deb dll dmg exe img iso msi msm msp safariextz;
application/pdf pdf;
application/postscript ai eps ps;
application/rtf rtf;
application/vnd.google-earth.kml+xml kml;
application/vnd.google-earth.kmz kmz;
application/vnd.wap.wmlc wmlc;
application/x-7z-compressed 7z;
application/x-bb-appworld bbaw;
application/x-bittorrent torrent;
application/x-chrome-extension crx;
application/x-cocoa cco;
application/x-java-archive-diff jardiff;
application/x-java-jnlp-file jnlp;
application/x-makeself run;
application/x-opera-extension oex;
application/x-perl pl pm;
application/x-pilot pdb prc;
application/x-rar-compressed rar;
application/x-redhat-package-manager rpm;
application/x-sea sea;
application/x-shockwave-flash swf;
application/x-stuffit sit;
application/x-tcl tcl tk;
application/x-x509-ca-cert crt der pem;
application/x-xpinstall xpi;
application/xhtml+xml xhtml;
application/xslt+xml xsl;
application/zip zip;
text/css css;
text/csv csv;
text/html htm html shtml;
text/markdown md;
text/mathml mml;
text/plain txt;
text/vcard vcard vcf;
text/vnd.rim.location.xloc xloc;
text/vnd.sun.j2me.app-descriptor jad;
text/vnd.wap.wml wml;
text/vtt vtt;
text/x-component htc;

URL Resource Path

These are additional paths appended to the end of the URL, divided by slashes. For example: http://demo.sepasoft.com/main/system/webdev/WebServicesAPI/getProductCodeList?filter=SA contains "/main", "/system", "/webdev", "/WebServicesAPI" and "/getProductCodeList" as resource paths.

URL Resource Path entities are created in the RESTful Configuration as shown to the right (they are appended in the order they are listed).

URL Query String

 These follow any resource paths, and follow a question mark. They have a key and a value. Using the above example, filter=SA is a query string. They are appended to the end of the URL, after any appended URL Resource Path strings.

URL Query String entities are created in the RESTful Configuration as shown to the right (they are appended in the order they are listed).

Request Body

This section can be created to represent an XML- or JSON-format Request Body. The XML Request Body can include XML attributes, as shown in the example below.

The above example is translated into the XML representation below and sent in the POST body to the remote web server:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<complexArray complexAttribute1="Hello" complexAttribute2="World">
		<simpleVal simpleValAttr1="1" simpleValAttr2="2">3</simpleVal>
	</complexArray>
</root>



IconFunctionDescription

Categorized  /  AlphabeticDetermines how the rows in the Request Message area are sorted.

Show/Hide Description AreaToggle to show or hide the Description Area underneath the main Request Message area.

Expand  /  CollapseWhen sorted as 'Categorized', then Expand and Collapse work on the rows in each of the categories.

Add New Item

When Add New Item is clicked, the following dialog box appears, to allow selecting the category of item to add.

Edit Selected Item

When Edit Selected Item is clicked, a dialog box with the settings for the selected row will appear.

Remove Selected ItemRemoves the selected row. Note: There is no 'undo' function for this.

Move Selected Item One Row Up / DownMoves the selected row in the direction of the arrow clicked.

Copy Selected RowCopies the selected row to a local clipboard (not the computer clipboard). This function applies only to the complex data type.

Paste Copied RowPastes the copied row in the local clipboard into the complex parameter. This function applies only to the complex data type.

Copy Sample Script

Copies the completed 'runWebService' scripting function required to run the RESTful Consumer to the computer clipboard (can be pasted anywhere).

Here is an example copied script pasted into the Script Console and executed. Note the returned Response Message on the right.


Description

Underneath the Request Message area is the Description Area. Click on a row in the Request Message area and information about the parameter in that row will be displayed.



Response Message


IconFunctionDescription

Categorized  /  AlphabeticDetermines how the rows in the Response Message area are sorted.

Show/Hide Description AreaToggle to show or hide the Description Area underneath the main Response Message area.

Expand  /  CollapseWhen sorted as 'Categorized', then Expand and Collapse work on the rows in each of the categories.

Add New Item

When Add New Item is clicked, the following dialog box appears, to allow selecting the category of item to add. This function applies only to complex and array data types.

Edit Selected Item

When Edit Selected Item is clicked, a dialog box with the settings for the selected row will appear.

Remove Selected ItemRemoves the selected row. Note: There is no 'undo' function for this.

Move Selected Item One Row Up / DownMoves the selected row in the direction of the arrow clicked.

Copy Selected RowCopies the selected row to a local clipboard (not the computer clipboard). This function applies only to the complex data type.

Paste Copied RowPastes the copied row in the local clipboard into the complex parameter. This function applies only to the complex data type.

Generate Response Body from JSON or XMLIf you already have a JSON or XML Response Message from the intended RESTful Provider, click this icon and then paste it into the popup dialog area. Click OK and it will be parsed to extract the Response Conversion rows required for the RESTful Consumer. The result will populate in the Response Message area.

Run Web Services Configuration

If you do not have a JSON or XML Response Message from the intended RESTful Provider, click this icon and a live Request Message will be issued (with the provided default values appended in the URL Query String). Upon receiving the Response Message, it will be parsed to extract the Response Conversion rows and populate in the Response Message area.

Make sure to click Save in Designer before clicking this Run Web Services Configuration button.


Description

Underneath the Response Message area is the Description Area. Click on a row in the Response Conversion area and information about the parameter in that row will be displayed.


The format of the Web Service Response Message can be set using the Response Conversion Item setting. Data types such as DateTime, Float4, Float8 has format options in a drop down menu, as shown.













  • No labels