Get Started with the Claromentis API

Using the Claromentis REST APIs you can manage many of the aspects of your Claromentis installation.

After reading through this guide, take a look at the API Reference to see all available API requests, or visit the tutorials for a more guided approach to using the APIs.

Before You Start

The Claromentis REST API is designed for developers, engineers, or anyone else who’s comfortable creating custom-coded solutions or integrating with RESTful APIs. If you're not familiar with REST or would like to learn more, take a look at our Introduction to REST guide.

If you'd prefer not to do your own development, or if you don't have developers in-house to do it, we also offer custom development services. Contact your account manager for more information on how to make use of our extensive experience with the Claromentis framework.

Resources

Resources are typically nouns like ‘users’ or ‘articles’ that you take actions on using supported HTTP verbs such as GET, POST and DELETE.

Access to the entire REST API is located at https://your-intranet-host-name.com/intranet/rest/.

A typical REST uri will look something like this:

https://your-intranet-host-name.com/intranet/rest/application_name/resource_type/other_parameters

For example, the uri to retrieve a Knowledgebase article with the ID of 12345 would be a HTTP GET request to:

https://your-intranet-host-name.com/intranet/rest/knowledgebase/articles/12345

Versions

As Claromentis applications are developed separately from the Claromentis framework itself, some applications may have multiple versions of its REST API. There are two main ways to specify which version of the API you want to use.

Version number in the URI

For example:

GET /intranet/rest/documents~v1/folder/23/info

Or...

GET /intranet/rest/documents/v1/folder/23/info

Version number in the HTTP header

GET /intranet/rest/documents/folder/23/info
X-API-Version: 1

Authentication

We have a dedicated article that details the two main forms of authentication that Claromentis uses.

HTTP Methods

The APIs supports 4 HTTP methods for interacting with resources:

GET

Make a GET request to retrieve data. GET requests will never cause an update or change to your data because they’re safe and idempotent.

POST

Use a POST request to create new resources. For example, make a POST request to a collection endpoint (like /lists) where the body of your request JSON is a new list.

PUT

Use a PUT request to create or update a resource.

DELETE

Make a DELETE request to remove a resource.

X-HTTP-Method-Override

Some Internet service providers don't allow PUT and DELETE requests. So it's also possible to pass these verbs in the X-HTTP-Method-Override HTTP header in a POST request. Claromentis will check this header and react to the verb correctly.

JSON

The Claromentis APIs only support JSON. Most POST and PUT requests require a valid JSON object for the body. The API Reference includes complete examples.