Get to Know a Feature: Network Communication

Igor Pro 7 improves upon the network communication features available in Igor Pro 6 in two important ways:

• Support for secure encrypted communication via SSL/TLS (https:// URLs)
• Feature rich communication using new URLRequest operation 

ENCRYPTED COMMUNICATION

In Igor Pro 6 the FetchURL function can be used to make an unencrypted http request but it is not possible to securely communicate using an encrypted https request. In Igor Pro 7, https is supported by both the FetchURL function and the new URLRequest operation. The secure layer is provided by the operating system, using Secure Transport on Macintosh and Secure Channel on Windows.

Support for encrypted communication not only improves security but it also allows Igor Pro 7 to communicate with a wide variety of web-based services, many of which require encrypted connections. ProgrammableWeb provides a list of many web application programming interfaces (APIs) that are available, a number of which are science related. Note that it may not be possible to use all web APIs from within Igor Pro 7, depending on how the API is implemented.

NEW URLREQUEST OPERATION

The FetchURL function available in Igor Pro 6 (and of course still available in Igor Pro 7) allows you to make a simple query to a web server and stores the response in a string variable, but for more complicated web requests this function is not sufficient. The new URLRequest operation can be used for these more complicated requests. Compared to FetchURL, URLRequest adds support for the following:

• Additional methods (eg. http POST, PUT, HEAD, and DELETE)
• Modifying http request headers
• Using a file or an Igor string as a source of data for the PUT or POST methods
• Saving the server's response directly to a file
• Controlling redirection behavior
• Proxy servers (this support is still experimental)
• Configuring request timeout
• Determining the server response code for the request
• Inspecting the headers returned by the server as part of the response

As an example of how the new URLRequest operation is useful, we'll use URLRequest to communicate with Stripe.com, a credit card payment processor. I'm using Stripe as an example because WaveMetrics uses Igor Pro 7 to communicate with Stripe as part of the ordering process. Yes, we love Igor so much that we've even built our business back-end software in Igor! The Stripe API is a REST style API that returns JSON formatted data.

AUTHENTICATION

Many web APIs require that you authenticate each request using a username and password or secret API key. The following function makes a request to the API using a demonstration key. If you execute the function, "Authentication successful" should be printed in the history window.

Function authenticate()
    String theUrl = "https://api.stripe.com/v1/charges"
    String user = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    String password = ""    // blank
    URLRequest/AUTH={user, password} url=theUrl
    if (V_flag == 0)    // No error
        if (V_responseCode == 200)  // 200 is the HTTP OK code
            print "Authentication successful"
        else
            print "Authentication failed"
        endif
    else
        print "Connection error. Authentication not attempted."
    endif
End

POSTING DATA

The last example used a simple GET request, which is typically used in a read-only fashion in which data is simply being retrieved from a server. However, it is often necessary to send data to a server using the POST method. The function below submits a charge using a POST request. Note that this code uses a test account and credit card number, so feel free to execute this code yourself. If you execute this function, "Charge successful" should be printed in the history window, followed by an identification string that could be used to refer to the charge at a later time.

Function postACharge()
    String theUrl = "https://api.stripe.com/v1/charges"
    String user = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    String password = ""    // blank
    String data = ""
    data += "amount=2000&"
    data += "currency=usd&"
    data += "source[object]=card&"
    data += "source[number]=4242424242424242&"  // test number
    data += "source[exp_month]=12&"
    data += "source[exp_year]=2027&"
    data += "description=\"Charge for igor.7@example.com\""
    URLRequest/AUTH={user, password}/DSTR=data url=theUrl, method=post
    if (V_flag == 0)    // No error
        if (V_responseCode == 200)  // 200 is the HTTP OK code
            print "Charge successful"
            
            // Get the id of the successful charge.
            String regExp = "\"id\": \"(.*)\""
            String id
            SplitString/E=regExp S_serverResponse, id
            printf "Charge id: %s\r", id
        else
            print "Charge failed"
        endif
    else
        print "Connection error. Charge not attempted."
    endif
End

HANDLING STRUCTURED TEXT

Most web APIs return (and sometimes take in) text of a specific format, typically XML or JSON. Igor Pro does not currently have any built-in support for handling either of these formats. XMLutils is a third-party XOP that may be useful for handling XML. JSON returned by web services is often relatively simple, and you may be able to parse it using Igor's string handling routines (such as SplitString, which was used in the example above). Adding built-in support for parsing JSON is something we're considering. If this feature would be useful to you, please send a note to support@wavemetrics.com to let us know.