Getting Started

APIs Everywhere!

So what is the API Sever and what does it do?

The API Server provides services to your Digital Platform. These services are known as workers. Some workers interact with the platform's database, some are used to send requests and receive data back from third-parties, and others provide functionality like your site login, generating forms, and handling workflow processes.

Workers are secured using IP restrictions (so some can only be called internally) and API Keys. You can call workers from your forms, End Points, workflow processes and site template code. You can also make some services public so that other people can send requests to your platform.

Each worker has its own API, described in the Worker Services documentation.

Making a Request

Let's get started! This example uses the Postcode worker which, in our standard platform setups, isn't secured and has a proxy set up so it can be called by your forms as users fill them in. Even if you don't have the worker connected to a postcode database or provider, you can still search for the GOSS Interactive postcode (PL6 7TL) and get results back.

You can read documentation for the postcodeSearch method in the postcodeSearch (postcode, provider) article.

From a Form

The forms designer has several fields you can use to call the API Server (you can also use functions in the form helper library). This is the Ajax Template field:

The field will call the postcode worker on the /apiserver/postcode URL. It will invoke the postcodeSearch, and pass in "PL6 7TL" as the value of the postcode parameter. The result of the call is displayed in a Handlebars template.

There's a form with a working example of this field related to this page.

From an End Point

When you want to call the API Server from an End Point, you can use the API Client library or callWorkerMethod in the End Point this object:

function(params, credentials) {
    var result = this.callWorkerMethod("postcode", "postcodeSearch", {
        "postcode": "PL6 7TL"
    });
    return result;
}

And the result:

{
    "jsonrpc": "2.0",
    "id": 1211,
    "result": {
        "jsonrpc": "2.0",
        "id": "_5",
        "result": [{
            "udprn": "18994206",
            "company": "Delta Engineering Plymouth LLP",
            "department": "",
            "line1": "Darklake View",
            "line2": "Estover",
            "line3": "",
            "line4": "",
            "line5": "",
            "town": "Plymouth",
            "county": "Devon",
            "postcode": "PL6 7TL"
        }, {
            "udprn": "18994215",
            "company": "Goss Interactive Ltd",
            "department": "",
            "line1": "24 Darklake View",
            "line2": "Estover",
            "line3": "",
            "line4": "",
            "line5": "",
            "town": "Plymouth",
            "county": "Devon",
            "postcode": "PL6 7TL"
        }, {
            "udprn": "18994208",
            "company": "Jennycrafts",
            "department": "",
            "line1": "Cranmere House",
            "line2": "21 Darklake View",
            "line3": "Estover",
            "line4": "",
            "line5": "",
            "town": "Plymouth",
            "county": "Devon",
            "postcode": "PL6 7TL"
        }]
    }
}

From Somewhere Else

You can also make requests to the API Server from external applications. The Postman (opens new window) is a free tool you can use to make requests and examine the responses.

If you have Postman you can copy the request in the image above and get results back from the Postcode worker on this website.

Next Steps

Believe it or not, that's the basics covered - you now know how to call an API Server worker service. The rest of this documentation builds upon the basics by looking at worker security and authentication, internal services, writing End Points, and detailed examples for specific workers like History and the iCM API itself.