Create Ticket My Tickets Post Discussion
Welcome
Login  Sign up
  1. Knowledge Base
  2. API
  3. API Overview

Tips for REST Integrations

TABLE OF CONTENTS

While we can't offer you advice on how to program your web service, below are some tips on how to best configure and test your work.

Re-running REST connectors

When testing out your web service against incoming data from our platform, you'll likely need our platform to send the same REST request over and over. Requests are generated from our platform by the REST connector's triggering event (e.g., by a new Form entry being captured). Capturing a new Form entry every time you want to test a REST request will be time-consuming, so instead you should reschedule a REST connector against an existing entry.  This way you can run the same REST connector job over and over again.

To reschedule a Form entry connector:

  1. Go to the Data area of the Forms On Fire web platform and search for your target Form entry
  2. Mouse over the target Form entry row in the Data listing, and click the "logs" link to show the Logs dialog.
  3. The Logs dialog shows you the various connector jobs run for the entry, including your REST connector.  
     You can reschedule the REST job by mousing over the REST connector log line and clicking the "reschedule" link.

Use RequestB.in to view REST requests sent by our platform

If you're not sure what exactly is being sent by our platform to your service, then a service like RequestBin.com provides a simple, free way to see the exact data sent. RequestBin (among similar services) gives you a URL that will collect requests made to it and lets you inspect them in a human-friendly way.
 The setup steps are simple:

  1. Head to RequestB.in and create a RequestBin.  Make sure you tick the "Private" checkbox to keep your data safe.
  2. Point your REST connector to the RequestBin.com URL and trigger your REST connector (e.g., by capturing a new Form entry or by rescheduling the connector on an existing entry)
  3. Give the connector a minute to be run and then review the REST request information over at your private RequestBin URL.

Should you use a custom REST body or not?

By default, our REST connectors will send data in one of our standard answer formats. If you want to connect a REST connector to an existing API on your systems, then you must specify a custom body on your REST connector, since our standard formats will not be compatible with your API.

Custom bodies are dynamically generated by our system against a JSON/XML template that you specify. The relevant answer/data values are injected into your template by using our standard Data Template syntax; this concept works similarly to a "mail merge" in Word.

You should definitely review our Data Templates documentation to understand how to handle concepts like repeating data.  See the "Outputting Data with Templates" section for more.

Custom bodies can take a while to get exactly right, usually through much testing; however, this does provide the most flexible way to integrate with existing APIs and services.

If you are building a brand-new web service from scratch, then we recommend you build your web service to work with one of our built-in answer formats. This will save you time in terms of having to design your own request format; instead, you can just work with ours immediately.

We provide three standard formats for outputting Form entry data:

  • "Flat" - provides a flattened output of Form entry data
  • "Rich" - provides a detailed hierarchical data output
  • "Raw"- provides a minimal hierarchical output

You can view these formats in action by choosing a format from the given dropdown on your REST connector and then testing the connector to gather the request result (e.g., using RequestBin.com above).

Another way to view these formats in action is via the API Explorer. Head over to the FormEntry/Search endpoint and use the AnswerFormat parameter to specify the desired response format.

Using SOAP XML 

Our platform supports the use of Simple Object Access Protocol (SOAP) XML in REST Connectors to POST or PUT to external APIs. 

A SOAP message is an ordinary XML document containing the following elements:

  • An Envelope element that identifies the XML document as a SOAP message
  • A Header element that contains header information
  • A Body element that contains call and response information
  • AFault element containing errors and status information

In order to use SOAP XML, you will need to customize the header of your POST or PUT request on your REST Connector. 

  1. Set the HTTP Action to POST or PUT and Data As to XML. 
  2. Enter the Destination URL.  You can test the example SOAP XML body we've provided below by using the Destination URL http://www.example.org
  3. Click the "Customize Headers" link at the top of the connector, Enter both a Name and a Value for SOAP XML:
    1. Name: Content-Type
    2. Value: application/soap+xlm
  4. Click the "Customize Body" link at the top of the connector. Enter a customized bocy for the SOAP XML. An example SOAP XML script is provided below.

Example SOAP XML Body: 

<?xml version="1.0"?><soap:Envelopexmlns:soap="http://www.w3.org/2003/05/soap-envelope/"soap:encodingStyle="http://www.w3.org/2003/05/soap-encoding"><soap:Body xmlns:m="http://www.example.org/stock">  <m:GetStockPrice>    <m:StockName>{{yourFieldOne}}</m:StockName>    <m:StockName>{{yourFieldTwo}}</m:StockName>    <m:StockName>{{yourFieldThree}}</m:StockName>  </m:GetStockPrice></soap:Body></soap:Envelope>












Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.