All workers support requests made using JSON-RPC 2.0 and a few, like Authentication and the File Store, have REST interfaces for making HTTP requests. Workers are secured to keys, which define IP restrictions and authentication requirements which must be met before a request can be made.
Service URLs
The API Server has a base URL, typically
The initial path segment after the port number identifies the worker to call. For example,
You can see a list of all of the worker service URLs of your Digital Platform from the iCM/API Servers home page, in the System Configuration section of the iCM Management menu.
So that public requests can be made to the API Server's ajaxlibrary a proxy has been defined in the platform:
Keys and Authentication
All API Server workers are bound to keys. You can manage your API keys in iCM from the API Server Security section of the iCM Management menu.
Some keys, coloured white in the explorer menu, only define IP rules (additional security settings and method filters are not checked and default credentials added to workers assigned to the key are not supplied) . For example, the "open" key has no IP restrictions, which means that anything can call the workers bound to it; the "internal key" has IP rules that restrict access to its workers to calls from within the API Server itself.
Other keys, the yellow ones in the explorer menu, define genuine API keys. These keys must be present in the requests to workers bound to them. IP rules can also be added to these keys.
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. Using end points as an example, that would 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.
Credentials
When you make a request to a worker you can supply additional credentials using HTTP basic authentication, or, if using one of our standard libraries, simply including a username and password. The credentials you include represent an iCM or site user. Credentials serve two purposes.
Firstly, they can add additional security to the use of the API key. The user identified by the credentials must meet the authentication requirements defined in the key's worker.
For example, this key gives access to the iCM API worker. As well as the key itself, the iCM API worker bound to it requires the credentials of an iCM user in the ADMINISTRATORS group to be supplied before access is given.
Secondly, credentials can be used by a service to impersonate a user. This grants the worker the same level of access to iCM content as that user, and also allows the worker to carry out tasks "in the name of" that user. For example, if the iCM API worker is used to create an article, the user included in your request will become the "owner" of that article and be listed in the iCM security logs and version history as the user responsible for its creation.
Supplying Default Credentials
When you create a connection to the API Server, either using the apiclient library, a form helper library function, or a workflow task, you can supply a user and password in the "options" object. The problem with this approach is that the password of this user will be visible, in plain text, in your form, End Point, or workflow model.
Rather than supplying credentials every time, you can set up the worker bound to your key with default credentials.
Now, whenever the key is used this worker will be supplied with credentials stored in a secure place in iCM. There's an example of this in the Making Requests article.
The Internal Key
Workers bound to the internal key only accept requests from another worker on the same API Server. This key provides the most secure way to restrict access to workers.
To access internal workers you need to supply the ID of the server you are working on when creating your API Client using the apiclient library. If you are working in End Points, use
If you are working in forms, set the "internal" flag as true for .utilCreateAPIServer, or use .utilServerAPIServerCall, which makes internal calls by default.
Keys, Credentials and Tokens
Checking keys and credentials is a potentially expensive operation. To improve performance, the API Server responds to the first successful request made to it with a token. A token is a UUID with a short lifespan which is used in place of the API key and credentials in subsequent requests.
If you are using one of the standard methods of communicating with the API Server the handing of tokens is performed automatically - the scripts your write needn't be aware of them. For example, if in an End Point you were to create an API Client:
var apiclient = require("apiclient");
var client = new apiclient.ApiClient({
"apiKey": "83A9ABB3-xxxx-xxxx-xxxx-9E2E7673137F"
});
Then invoke that client:
var articleData = client.invoke("icmapi", "CSArticle_get", {
"get": "*",
"set": {
"ArticleID": 21
}
});
All subsequent requests to that client actually use a token, rather than rechecking the key and credentials:
var createArticle = client.invoke("icmapi", "iCM_obj_articleUpdate", {
"attributes": {
"ArticleStruct": ArticleStruct
}
});
JSON-RPC 2.0 Requests
The majority of the requests you make to the API server will use JSON-RPC 2.0, a remote procedure call protocol based upon JSON and described in detail at JSON-RPC2 specification (opens new window).
A request is a JSON object with the following format:
{
"id": id,
"method": method,
"params": {params},
"jsonrpc": "2.0"
}
- id must be a string or an integer and should be unique for a particular service. A simple incrementing integer prefaced by a unique client ID is the recommended format.
- method is the method to be called and must be defined for the service being accessed.
- params are the method parameters and must be an object (ie the parameters are named). If a method takes no parameters then use an empty pair of braces.
The response is also a JSON object:
{
"id": id,
"result": {result},
"jsonrpc": "2.0"
}
Or in the case of an error:
{
"id": id,
"error": {
"code": code,
"message": message
}
"jsonrpc": "2.0"
}
- id is the same as that of the request.
- result can take any legitimate JSON form, but in general it will be an object with result or error properties. These are used to return the result of the method call or any error occurring during the execution of the method call.
- code and message are used to indicate an error in the JSON-RPC2 protocol and use the error codes described in JSON-RPC2 specification (opens new window). Note that a missing method or the wrong type of arguments are treated as protocol errors.
JSON-RPC2 doesn't allow result and error objects as top level items in the same response, but no such limitation exists within the result object itself. An example of a legitimate response is:
{
"id": "client1",
"result": {
"result": "A string result",
"error": null,
}
"jsonrpc": "2.0"
}
When you're working in forms, End Points, workflow processes or site frameworks, the platform provides are range of libraries and functions you can use to make these requests. The Making Requests article looks at each of these scenarios in turn.
Share this page
