Get Started

This documentation will walk you through authentication and making your first API call. We will call the View Banners (XMADOWST) endpoint within this documentation.

Audience

This documentation is intended for users who understand how to make REST API calls. It is assumed you are familiar with making HTTP web requests in your preferred programming language. If you’re unfamiliar with this process and would like to use Postman instead, see the Postman Tutorial.

URL

Each call uses an HTTP POST to a URL using the following template:

https://{centralstation.securemcloud.com}/rest/rest.php?dataSource=methods&*view=xmsubmit

Contact the central station if you don’t know their domain.

Authentication

Each call you make within MADE will need to contain authentication information to validate the request.

Headers

The body of the POST will include form data describing the action you want to take. The other pages in this documentation describe the available actions. The request is authenticated by adding custom HTTP headers. A description of how to calculate these headers follows.

HeaderTypeDescription
X-DICE-APPKEYstringName of your program. This can be any string of characters.
X-DICE-USERNAMEstringThe username assigned to you by the central station.
X-DICE-DATEstringThe current time in DDMMYYYYHHMISS format. Example: 03012024090823.
X-DICE-NONCEstringA random string of 20 letters. This is generated with each request.
X-DICE-DIGESTstringCombines the above information along with the password provided by your central station into a single string ending with a new line character (\n). You then apply a sha1 hash to the resulting string and encode the result in hexadecimal to produce the Digest. A Digest example is below.

X-DICE-DIGEST example 

ourclientdocumentation03012024090823nE3MSLaXYb23rp7DTDchsecretpassword\n
|-------||-----------||------------||------------------||------------|||
 ^        ^            ^             ^                   ^            ^ new line 
 |        |            |             |                   - password     (ascii character 10)
 |        |            |             - nonce
 |        |            - date
 |        - username
  - appkey

This would result in a Digest of: 1a0c0a42e5adb089ef2a8707029aad2450fbf83b

Making a call

Below is a cURL example of calling the View Banners (XMADOWST) endpoint. This endpoint allows users to view existing banners on a client’s system.

Example request 

curl --location "https://{centralstation.securemcloud.com}/rest/rest.php?dataSource=methods&*view=xmsubmit" \
--header 'X-DICE-APPKEY: ourclient' \
--header 'X-DICE-USERNAME: documentation' \
--header 'X-DICE-DATE: 03012024090823' \
--header 'X-DICE-NONCE: nE3MSLaXYb23rp7DTDch' \
--header 'X-DICE-DIGEST: 1a0c0a42e5adb089ef2a8707029aad2450fbf83b' \
--header 'Accept: application/json' \
--form '*setMethod="XMADOWST"'

Example response

Below is a JSON example of what the system will return when calling XMADOWST.

{
    "XMADOWST": [
        {
            "DOWN_MESSAGE": "SIA DEV HAS FAILED. CONTACT YOUR SUPERVISOR.",
            "DOWN_COLOR": "6C",
            "COLOR": "6C",
            "DOWN_TIME": "118.726"
        },
        {
            "DOWN_MESSAGE": "SURGARD #1   DV HAS FAILED. CONTACT YOUR SUPERVISOR.",
            "DOWN_COLOR": "6C",
            "COLOR": "6C",
            "DOWN_TIME": "27.73033"
        },
        {
            "DOWN_MESSAGE": "MATRIX TASK Gt HAS FAILED. CONTACT YOUR SUPERVISOR.",
            "DOWN_COLOR": "6C",
            "COLOR": "6C",
            "DOWN_TIME": "94.71262"
        },
        {
            "DOWN_MESSAGE": "MATRIX TASK Gu HAS FAILED. CONTACT YOUR SUPERVISOR.",
            "DOWN_COLOR": "6C",
            "COLOR": "6C",
            "DOWN_TIME": "96.57096"
        }
    ]
}

The value of this key will be an array of similar objects in the case that more than one row is returned or a single object in the case that exactly one row is returned. The details of the response format can vary and will be documented along with the endpoint.

← Postman Tutorial
Supplemental Information →