Calling End Points Externally

End points can be deployed to one or more workers in the API Server. The keys these workers are bound to determine where they can be called from and whether or not an API key should be provided with the request. This article looks at the public ajaxlibrary and the securelibrary.

Website Proxying and IP Addresses
All external requests to API Server workers are proxied through your website. That means that as well as the IP restrictions set up on API Keys in iCM, only the worker URLs defined by the site proxy are accessible. For end points that will be the ajaxlibrary and securelibrary. However, that does mean that all requests to these worker will appear to come from 127.0.0.1, so setting additional IP restrictions won't work.

Unsecured Public End Points

The ajaxlibrary end point worker is bound to the OPEN key. It is completely unsecured and can be called by absolutely anything capable of making JSON-RPC requests to your site. That's not to say you won't have other restrictions in place (IP restrictions on your staff intranet for example) but it's best to assume that end points deployed here are on your public website and open to the internet. Needless to say, think about security and what your end point does before deploying here.

You can access the ajaxlibrary on https://[my-website.com]/apiserver/ajaxlibrary

Making Requests

Requests to the ajaxlibrary use standard JSON-RPC. The method you call is the full name and namespace of your end point.

For example, this is a public end point on the documentation site used for testing and examples. You can call it on https://docs.gossinteractive.com/apiserver/ajaxlibrary.

It's name is formstraining.dummyData.returnSomeDataAjax.

Using something like the Postman (opens new window), you can make a request and see the response.

A parameters schema has been added to validate the requests made:

Try making a request. You'll receive an error if you have additional parameters, or if "request" is anything other than "object", "string", "date", "array", or "number".

Secured Public End Points

End points can also be deployed to the securelibrary. By default, this worker is only available internally, but can also be bound to any keys you create yourself. To access end points deployed to it, create a new API key, then include that key with requests.

API keys are added to the x-api-key header in your requests. Using Postman again, you can add the header like this:

The URL for the securelibrary on the docs site is https://docs.gossinteractive.com/apiserver/securelibrary.

A dummy end point called formstraining.dummyData.returnSomeDataSecure has been deployed there (it's a copy of the Ajax one above).

Use EE0BAFB9-9D31-4F61-9DE0-A13E5ECB51A5 as the API Key to access it.

Method filters (see below) have also been set up, so if you try to access anything other than the dummy end point you'll receive a 401 response.

There's more information about creating keys in the API Server Security and URLs, Keys and Authentication articles.

Method Filters

To further secure your publicly available services you can also add method filters to the workers bound to a key. These filters use regular expressions to limit the methods that can be called.

This is really useful when combined with end points deployed to the securelibrary. It means you can create multiple API Keys, add the securelibrary to them, then restrict the end points that someone can call using each key (without method filters the same key could potentially be used to call all end points deployed to the securelibrary).

This is how the securelibrary example above has been set up: