Getting Started

APIs Everywhere!

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

At its most basic, an API is a way for different pieces of software to communicate with each other. The API Server is a central point in the platform that hosts and publishes all of the APIs that can be used to interact with the platform.

The services that API Server provides to your Digital Platform are known as workers. Most 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. A special category of workers even let you write your own APIs and publish them as End Points.

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 API Server Workers documentation.

Making a Request

Let's get started!

The basic structure to call a worker on the API Server is https://<subsiteURL>/apiserver/<worker-name>.

This example uses the Postcode worker which, in our standard platform, 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.

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 example uses the HTML Ajax Template field to make the request.

This form will search for the GOSS postcode, and display the results it gets back from the Postcode worker.

1. Add a text input field called "Postcode"to the form. The postcode entered into this field will be sent to the Postcode worker
2. Add a HTML Ajax template (from the display category)

The field will call the postcode worker on the /apiserver/postcode URL. It will invoke the postcodeSearch, and pass in the value of the #POSTCODE# field as the value of the postcode parameter.

3. The result will be displayed in the field's Handlebars template

Example

You can download and import the example above into your own forms designer (you'll need to extract the zip file and import the xml file)   (ZIP) [2KB]. The working form is also related to this page.

Also, be aware that the example is slightly artificial. We have the Address Lookup form field which does all of the hard work for you!

Next Steps

Believe it or not, that's the basics covered - you now know how to call an API Server worker. 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.