CWork API Documentation (v1.9)

CWork has a REST api that you can request to obtain data about your DNC or MDC installation.

Licensing ¶

To fully or partially access CWork’s API, you need to have an according license. If you don’t or if you just don’t know, contact your reseller.
This documentation will tell you which license you should acquire to access each resource. Search for the license required property.

Here are the existing API license types :

• monitor

• dnc
  More to come…

In the following documentation, any means that any API license module will give you access to the specified function.

Authentication ¶

As from v1.2 CWork’s API requires HTTP Basic Authentication (see RFC-2617 for more information on HTTP Authentication standards).

• The user field of the Authorization header will need to be the API key corresponding to the desired CWork user.

• The password field of the Authorization header shall be ignored.

To obtain the API Key corresponding to the CWork user, please go to the user management panel (Tools > Preferences > ‘User and groups management’), double-click on the desired user and copy the content of the API Key field.

HTTPS ¶

As from v1.2 CWork’s API can work either over HTTP or HTTPS. Note that it cannot work on both protocols simultaneously. Default will be HTTPS.

In this case, the only purpose of using HTTPS is communication encryption so self-signed certificates are used. Make sure to disable certificate verification on your client.

To disable HTTPS, please go to CWork’s engine preferences panel (Tools > Preferences > ‘Communication Services’), uncheck the HTTPS checkbox and apply changes. You will need to restart smmCApi.

API versioning ¶

You can specify witch API you want to query by adding the version identifier in the HTTP Accept Header. Here is an example :

Accept: application/json+v1

Here is the matrix of CWork’s version and API version availability.

Pagination ¶

To avoid returning too big responses, some resources of this API include URI parameters-based pagination. Example: Documents list

The limit parameter will allow you to indicate the maximum item count you want in the resource list. If you omit this parameter, a default value will be used based on the resource. NB: the limit value will be capped to a fixed value based on the resource.

The page parameter will allow you to specify which page of items you want to get. Example: if you set limit to 100 and page to 3 you will get items from 200 to 299.

Error codes ¶

CWork uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an internal error with CWork server.
Additionally, we will provide you an Error code and a human-readable message providing more details about the error.

Here is the list of the currently existing errors :

About data types ¶

This section will describe all you have to know about the data formats we use and how to interpret them. We will try to be as consistent and predictable as possible regarding the use of these data types.

Strings ¶

All strings within CWork’s API are UTF-8 encoded.

Dates & times ¶

All dates within this API will be provided as ISO8601 format including all date time and time zone designators. Here is an example :

2015-06-30T17:19:00.000Z

This example shows the date format for June the 30th, 2015 at 5:19 PM in the UTC time zone.

Take the following returned body as an example :

{
    "LastPing" : "2023-06-30T17:19:00+01:00"
}

The server is as we see located in the GMT+1 timezone. For example, in France.

If the server is located in Shanghai, you would get :

{
    "LastPing" : "2023-06-30T17:19:00+08:00"
}

As the Shanghai’s timezone is GMT+8.

This way you can use the API and build an app usable all around the world without taking time zones in consideration (as long as your code handles it automatically).

Durations ¶

All durations within this API will be provided in seconds.

Colors ¶

All colors within this API will be described in hexadecimal (HEX) format. Here are a few examples of common colors

Files ¶

All files transmitted via the API (inbound or outbound) will be exchanged in a common folder in CWork’s working directory under /Temp/API-io/. CApi will automatically create this folder at startup if it doesn’t exist.

For example, when making a GET request to the version endpoint with the include_file parameter set to true, the system will copy the desired file in /Temp/API-io/ and retrieve the temporal name in the JSON response body along with the MD5 hash of the file. The client application will then be able to get it from here and check its integrity.

It’s the client application responsibility to delete the file in /Temps/API-io/ when it’s no longer used. If it’s not, then the system will delete it after 10 minutes.

Generated by aglio on 03 Sep 2024