Web services: hosting a Web service technical principles

Note: You may wish to begin with this overview of Web services, and knowing how to call a Web service will be helpful before attempting this material.

Run this example Academic RIO Device Web service project to get an idea of what you can accomplish – this example serves the states of onboard sensors and system information to a remote client, and allows the remote client to control the onboard LEDs.

Technical principles

Fundamental concepts

• A “Web service” uses the same infrastructure as the web, i.e., web servers and clients, HTTP, URLs, and so on, but is intended for machine-to-machine exchange of specific information.
• LabVIEW VIs that implement web service behavior are located under the “Web Resources” virtual folder of the LabVIEW project. These VIs are known as “method” VIs. A method VI retrieves values from the URL query string (if needed and available), implements the behavior of the web service, e.g., performs a calculation, reads one or more sensors, captures an image, reads an onboard file, and so on, and finally generates the web page content to be delivered back to the client.
• LabVIEW provides two techniques to retrieve URL query string values and to return web page content generated by the VI:
  • “Terminal” – The block diagram uses front-panel controls connected to the VI’s icon frame to retrieve query string values. The front-panel control name corresponds to the query string name. Similarly, the front-panel indicators generate the web page content as either plain text, HTML, JSON, or XML. This technique is quick and simple, but the output format is limited.
  • “Streaming” – The VI can return output under your complete control, and can also return non-text output such as images and audio. These VIs require a little more effort to implement because they require the following elements:
    • Web service request front-panel control (must be connected to a terminal on the icon connector),
    • One or more “Read Form Data” VIs to read the name/value pairs in the GET query string of the URL,
    • Block diagram code to process the web service request, possibly including data processing, calculations, file I/O, analog I/O, digital I/O, etc.
    • “Set HTTP Response MIME Type” VI to specify how the remote client is to interpret the response from the web service, e.g., plain text, HTML code, image file, JSON code, etc., and
    • “Write Response” to send the web service information (i.e., a “web page”) to the remote client.
• Web services return structured information most often encoded as ASCII strings in XML (Extensible Markup Language) and JSON (JavaScript Object Notation; pronounced “JAY-suhn”). Use the LabVIEW function “Flatten To JSON” with the “streaming” output technique to accept a data cluster with named values to generate the JSON string. The cluster may include arrays and nested clusters with some limitations; see the help page for details.
• Security issues – LabVIEW Web Services on the Academic RIO Device does not support SSL; keep this in mind if using passwords or API keys because they are not secured.
• A LabVIEW Web service can also serve static web pages, for example, a default “index.html” page. See the excellent tutorials at http://www.w3schools.com to learn how to create HTML code.
• The “interactive.html” page in the hands-on demo uses JavaScript to implement the interactive behavior, i.e., the page refreshes whenever you enter a new value for the LED hex code. See the NI Community tutorial Web Services Getting Started Series and in particular the page Exploring Update Methods to learn more.

LabVIEW implementation of a Web service client

The following step-by-step video tutorial shows you how to build from the ground up a Web service similar to the one demonstrated earlier. This example Web service includes endpoint URLs to report the system date and time as well as the values of onboard devices (accelerometer and pushbutton), to set the onboard LEDs to a desired pattern, and to retrieve a webcam image with the option of selecting its dimensions and automatically refreshing the image once every five seconds. The tutorial also illustrates how to use the basic terminal-based technique (use front-panel controls and indicators connected to the icon frame) to retrieve query values and to return text, HTML, and JSON strings, and the stream-based technique to take control of the exact appearance of returned text and to serve other types of content such as a JPEG image.

1. Create the LabVIEW project framework: create a new Academic RIO Device project, add a new “Web Service” called “API”, and create “Web Resources” folders for external devices (webcam), onboard devices (accelerometer, LEDs, and pushbutton), and system information (time and date):

   https://youtu.be/vFzborQdM7s?start=0&end=153 (2:33)

2. Create the “system/date” method VI; use the “terminal” output type to serve the system date as simple text to the web service client:

   https://youtu.be/vFzborQdM7s?start=153&end=342 (3:08)

3. Create the “system/time” method VI; use the “streaming” output type to control the exact format of the information returned to the client:

   https://youtu.be/vFzborQdM7s?start=342&end=579 (3:56)

4. Create the “onboard/pushbutton” method VI. Use the “terminal” output type to return the pushbutton state as an HTML-formatted web page:

   https://youtu.be/vFzborQdM7s?start=579&end=754 (2:54)

5. Create the “json/onboard/accelerometer” method VI. Use the “terminal” output method to return the three-axis accelerometer values as a JSON string in both cluster and array formats for the sake of comparison:

   https://youtu.be/vFzborQdM7s?start=754&end=1059 (2:33)

6. Create the “onboard/LEDs” method VI. Learn how to retrieve the desired LED state from the endpoint URL query string using the “terminal” technique:

   https://youtu.be/vFzborQdM7s?start=1059&end=1368 (5:05)

7. Create the basic “external/webcam” method VI. Learn how to using the “streaming” output type to return a JPEG image to the client:

   https://youtu.be/vFzborQdM7s?start=1368&end=1697 (5:08)

8. Refine the “external/webcam” method to accept image dimensions from the URL query string:

   https://youtu.be/vFzborQdM7s?start=1697&end=2072 (5:29)

9. Refine the “external/webcam” method to cause the browser to automatically refresh the page (which requests a new image) every few seconds by setting the “Refresh” field to the HTTP header:

   https://youtu.be/vFzborQdM7s?start=2072&end=2208 (2:16)

10. Publish the web service to make it always available, even after a power cycle. Also view the site map for the URLs of all available method VIs:

    https://youtu.be/vFzborQdM7s?start=2208&end=2319 (1:53)

For more information

1. LabVIEW Web Services FAQ (http://www.ni.com/white-paper/7747)
   Frequently asked questions and answers about LabVIEW Web Services implementation.
   
2. JSON Basics: What You Need to Know (http://www.elated.com/articles/json-basics)
   Describes JSON syntax and how to form and parse JSON strings.
   
3. The JavaScript Object Notation (JSON) Data Interchange Format (https://tools.ietf.org/html/rfc7159)
   Produced by the Internet Engineering Task Force (IETF), this document summarizes JSON syntax specifications and provides some examples.