Webservices

These screens shape everything IMan sends to a web API. The four screens under Setup > Webservices describe how to talk to a service. The readers, writers and lookups that use the service then only have to say what to send.

Screen	What it holds
Basic Authentication	A named set of HTTP headers that authenticate a request, for services that take a token or a user name and password
OAuth 2.0 Authentication	How to obtain an access token, two-legged or three-legged, and which header carries it
Webservice Behaviour	The base URL, the authentication to use, request headers, throttling, paging, error handling and tracing for one service
Webservice Lookups	A GET request whose result is returned by the WebserviceLookup function

A behaviour ties them together. It names an authentication, and a reader, writer or lookup names the behaviour. The Http Headers control appears on every one of these screens. JPath is the syntax for pointing into a JSON response wherever a screen asks for one.

The Webservices Cookbook works through these screens against real services. Each page here is the field reference for the matching cookbook article.

URL checks

IMan checks every URL box on these screens as you type, and shows a warning beneath the box when the URL cannot be used. The URL must be absolute, use http or https and name a host. It must not point at a loopback, link-local or cloud-metadata address. Addresses on a private LAN are allowed, so an on-premise service is fine. Where a URL may carry a placeholder, such as a lookup's Query Url, the placeholder can appear in the path or the query string but not in the host or port.

The warning is advisory while you type. IMan applies the same rule when you save or test the record, so you cannot store a URL that fails it.

JSON (JavaScript Object Notation)

JSON is the text format most web APIs use to send and receive data. It has largely replaced XML. It is human-readable and built from three constructs: key-value pairs, objects and arrays.

Key-value pairs

The fundamental element of JSON is the key-value pair, or property, which associates a value with a name. The value can be a base type such as a string, a number or a Boolean, or a complex type such as an object or an array. You write the pair as the name in double quotes, a colon and then the value.

"name": "text value",
"integerproperty": 5,
"booleanproperty": true,
"dateproperty": "2015-01-21T12:10:20.000Z"

Objects

An object is an unordered collection of key-value pairs enclosed in curly braces. Objects can be nested inside other objects. This example has a customer object nested inside an order:

{
  "order_number": "1028",
  "token": "3b26b5ecd992012ac7a5e609f2d3379e",
  "customer": {
    "email": "[email protected]",
    "first_name": "Terry",
    "last_name": "Henry"
  },
  "site": "FR011",
  "shopifyid": 126627282
}

Arrays

An array associates several values with one name. The values can be base types or objects. You write the array as a comma-separated list inside square brackets.

An array of text values:

"email_addresses": ["[email protected]", "[email protected]"]

An array of objects:

"people": [
  { "name": "John Doe", "age": 29 },
  { "name": "Anna Smith", "age": 24 },
  { "name": "Peter Jones", "age": 39 }
]

JPath reads a value out of a structure like this.