While we can't offer you advice in terms of 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 rather 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:
- Go to the Data area of the nomorePAPER web platform and search for your target Form entry
- Mouse over the target Form entry row in the Data listing, and click the "logs" link to show the Logs dialog.
- 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 RequestB.in provides a simple, free way to see the exact data sent.
RequestBin (and similar services) gives you a URL that will collect requests made to it and lets you inspect them in a human-friendly way.
The steps to setup are simple:
- Head over to RequestB.in and create a RequestBin. Make sure you tick the "Private" checkbox to keep your data safe.
- Point your REST connector at the RequestB.in url and trigger your REST connector (e.g. by capturing a new Form entry or by rescheduling the connector on an existing entry)
- 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, but 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 flatted 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, then testing the connector to gather the request result (e.g. using RequestB.in 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.