Developers

How to use the Fiix API without an SDK


Table of Contents

Introduction


Fiix’s API can still be consumed without using one of our SDKs. In order to do this, this can be done by making HTTP requests and receiving HTTP responses, and creating and parsing JSON payloads. This guide assumes that you are familiar with making HTTP request, including defining URL parameters, request bodies, and request headers, and receiving responses. Further it is expected you are familiar with construction and parsing of JSON payloads.

Please note that while Fiix will frequently make changes to the API, every effort is taken to ensure that these changes are additive and backwards compliant. As such, your implementation should ignore unrecognized properties when parsing JSON.


API Request Overview


All requests to Fiix’s API have a few things in common.

First, they are all to https://[your subdomain].macmms.com/api/...

The should all specify the following url parameters:

Name Description
action For CRUD requests, the request class (e.g. FindRequest). For RPC requests, must be RPCRequest.
service Must always be cmms
timestamp The date and time the request was sent, in Unix Epoch milliseconds
appKey Retrieved from your API Keys, starts with macmmsackp, not needed for guest/unauthenticated requests
accessKey Retrieved from your API Keys, starts with macmmsaakp, not needed for guest/unauthenticated requests
signatureMethod Must always be HmacSHA256, not needed for guest/unauthenticated requests
signatureVersion Must always be 1, not needed for guest/unauthenticated requests


All requests must use the HTTP verb POST.

All requests must have a Content-Type header with a value of text/plain.

All requests must be in UTF-8 encoding.


Authenticating a Request

Most requests to Fiix APIs require authentication. Fiix does this by verifying a signature that must be provided in the Authorization HTTP Header.

To generate the signature, first, be sure to include the URL parameters specified above. First generate a secret spec using your api key’s secret key. Take the full URL, minus the protocol and protocol separator, and generate the hmac using the secret spec.

Most languages have libraries to generate HMAC’s, it is recommended to use a well known and trusted library for this rather than implement it yourself. The Java Fiix’s open source SDK uses to generate this is below, for reference:

                
    //Message is request URI
    String message = tp.uri; 
    //Trim off protocol
    if (message.indexOf("http://") == 0)
    {
        message = message.substring("http://".length()); 
    }   
    else if (message.indexOf("https://") == 0)
    {
        message = message.substring("https://".length()); 
    } 
    //Get Message bytes as UTF-8
    byte[] messageBytes = message.getBytes("UTF-8"); 
    //Get secret key bytes as UTF-8
    byte[] credentialsSecretKeyBytes = getCredentials().getSecretKey().getBytes("UTF-8"); 
    //generate the signing key
    SecretKey signingKey = new SecretKeySpec(credentialsSecretKeyBytes, "HmacSHA256"); 
    //generate the MAC
    Mac mac = Mac.getInstance("HmacSHA256"); 
    mac.init(signingKey); 
    //get the signature
    byte[] hmac = mac.doFinal(messageBytes);
    String hmacString = new String(Hex.encodeHex(hmac)).toLowerCase(); 
    return hmacString;
                
            


Request Body

All requests to the API are either CRUD Requests (CRUD stands for Create, Read, Update, Delete), or RPC Requests (Remote Procedure Call). These requests must all be in JSON and have the following common fields:

Name Description
_maCn For CRUD requests, the request class (e.g. FindRequest). For RPC requests, must be RPCRequest.
requestId Optional field to indicate a consumer identifier for the request. This must be a number. It should not repeat within a 10 minute window, though Fiix does not enforce this. It is useful for debugging.
requestSentUnixTime The date and time the request was sent, in Unix Epoch milliseconds
clientVersion An object detailing the client version. This should match to the sdk version available when you write your API integration.
clientVersion.major Major version of the client.
clientVersion.minor Minor version of the client.
clientVersion.patch Patch version of the client.

API Response Structure


All responses have a Content-Type header with a value of text/plain;charset=utf-8.

All response bodies will be in UTF-8 encoding.

All responses are in JSON and contain the property _maCn with a string value of the appropriate response for the request. Responses that return objects, e.g. FindResponse will contain an objects property with an array of the returned entities. Each of these entity representations will always at have the id property, and a className property defining the type of response returned. Additional properties relevant to the response type will also be included, details on these follow below.

Error Response

In the case of an error occurring during the processing of a request, an error response will be returned.

This response will contain an error object with the following properties:

Name Description
leg Indicates which part of the request processing failed, typically this will be SERVER_REQUEST_PROCESS.
code An error code.
message Any message attached to the error.
stackTrace A stack trace of the issue encountered. Please be sure to include this if you suspect you have encountered an issue.


Please note that as our API is not RESTful, errors are still returned with a 200 HTTP Status. The presence of the error object in the response object indicates whether the request was successful or not.

CRUD Request


CRUD requests are used to retrieve or modify state within Fiix. All requests must be in JSON format, and contain the field className. Please refer to the reference guide on the details of these requests.

Name Description
className The String representing the identifier for a specific Business Object.


Add Request

Executes an add request, analogous to a CRUD create request, additional fields for this request are in the table below.

Name Description
fields The fields to be returned in the JSON Response. Each field is a String. The list is comma-separated.
object The object representing the parameters to be used for the action to be run on the Business Object.

Find Request

Executes a find request, analogous to a CRUD read request, additional fields for this request are in the table below.

Name Description
fields The fields to be returned in the JSON Response. Each field is a String. The list is comma-separated.
filters An array of filters for restraining the query to objects matching some conditions.
orderBy The field to use to sort the results.
startIndex Offset used for the pagination of the results.
maxObjects The number representing the limit of the number of items returned.

Change Request

Executes a change request, analogous to a CRUD update request, additional fields for this request are in the table below.

Name Description
fields The fields to be returned in the JSON Response. Each field is a String. The list is comma-separated.
object The object representing the parameters to be used for the action to be run on the Business Object.
changeFields The fields that are to be used for the action. The list is comma-separated.

Remove Request

Executes a remove request, analogous to a CRUD delete request, additional fields for this request are in the table below.

Name Description
id The id representing the specific instance of the Business object to run the action on.

CRUD Response


All CRUD Responses share 3 common properties:

Name Description
_maCn A string value of the appropriate response type for the request.
serverVersion The object describing the API version with several properties, including major, minor, patch, and preRelease versions.
error The object representing detailed information if the Request fails. Details include: leg, message, code, stackTrace. See the Failure Response case below for more details.


Add/Change Response

The Add and Change responses have identical JSON structure, consisting of the added or updated object and the count.

Name Description
object The object representing the Response object according to the action to be run on the Business Object. This Response object may contain several properties including className, id, strDescription, strName, and more.
count The integer representing the number of objects returned in the Response Object.

Find Response

The Find responses shares a similar JSON structure.

Name Description
objects The array of objects representing the Response object according to the action to be run on the Business Object. This Response object may contain several properties including className, id, strDescription, strName, and more.
totalObjects The integer representing the number of objects returned in the Response Object.

Remove Response

The Response object may include the following properties:

Name Description
count The integer representing the number of objects returned in the Response Object.


RPC Request


All RPC requests consist of 3 properties

Name Description
name The String representing the identifier for a specific Business Object. Supported RPC names include: Calendar, DashboardWidget, GetAccessibleSites, GetTimezone, Ping
action The String representing the identifier for a specific Business Object method.
parameters The object representing the properties to be used when executing the method.


RPC Response


Upon executing a successful RPC Request, the Response returns a RPC Response object. In this case, see the below table and the code example on the right to see the returned object.

The Response object may include the following properties:

Name Description
serverVersion The object describing the API version with several properties, including major, minor, patch, and preRelease versions.
object The object representing the Response object according to the action to be run on the Business Object. This Response object may contain several properties including className, id, strDescription, strName, and more.
count The integer representing the number of objects returned in the Response Object.
error The object representing detailed information if the Request fails. Details include: leg, message, code, stackTrace. See the Failure Response case below for more details.


Further Details and Examples



Use Postman Client to access Fiix API

Please download and import the request collection in your Postman client from here

After importing the collection please follow the instructions below:
  1. Edit the collection

    edit-collection
  2. Navigate to the pre-request scripts section and make sure it's populated as displayed below
    this is where the Authorization header is computed

    pre-request-script

    The script above computes the Authorization header and places the token value in a variable named auth

    auth-header

  3. Navigate to the variables section and set the variables as per your tenant's configuration
    Checkout section on How to get your API access keys ?

    script-variables

  4. That's it, now let's fire our first API request to create an Account; a successful response should return id field of the created Account,
    as show below

    add-account-response

CRUD Example

The following is an example of an Add request sent to

https://[your subdomain].macmms.com/api/?action=AddRequest
&service=cmms
&appKey=[your app key]
&accessKey=[your access key]
&signatureMethod=HmacSHA256
&signatureVersion=1


JSON Description
Add Request Body(Example):
                            
    {
	  "_maCn" : "AddRequest",
	  "clientVersion" : {
	    "major" : 2,
	    "minor" : 8,
	    "patch" : 1
	  },
	  "className": "Account",
	  "fields": "id, strCode, strDescription",
	   "object": {
	        "strCode": "Account1",
	        "strDescription": "Checking Account",
	        "className": "Account"
	    }
	}
                            
                        
_maCn:     Specifies the request type

fields:     Specifies the fields that will be added within the new

className:     Specifies the Object to be created

object:     Provides the values for the object, using the fields described previously ("id" is generated and therefore does not need to be specified)

Curl request:
			                
$ curl -d '{"_maCn":"AddRequest","clientVersion":{"major":2,"minor":8,"patch":1},"fields":"id, strCode, strDescription","className":"Account","object":{"strCode":"Account1","strDescription":"Checking Account","className":"Account"}}' -H "Content-Type: text/plain" -H "Authorization: myAuthorisationKey" -X POST "http://mydomain.fiixserver.com/api/?action=AddResponse&appKey=myAppKey&accessKey=myAccessKey&signatureMethod=HmacSHA256&signatureVersion=1"
			                
			            
Add Response Body (Example):
                                
    {
	  "_maCn" : "AddResponse",
	  "serverVersion" : {
	    "major" : 2,
	    "minor" : 3,
	    "patch" : 1,
	    "preRelease" : "alpha"
	  },
	  "sync" : {
	    "revision" : 0,
	    "needToSync" : false,
	    "dateLastUpdated" : 1560885219000
	  },
	  "object" : {
	    "className" : "Account",
	    "id" : 57138,
	    "strCode" : "Account1",
	    "strDescription" : "Checking Account",
	    "strUniqueKey" : "Account1",
	    "new" : false,
	    "uideleted" : false,
	    "dirty" : false
	  },
	  "count" : 1
	}
                                
                          
_maCn:     Specifies the request type.

serverVersion:     Provides information about the server returning the response.

object:      The newly added object.

count:      The count of added object(s).

Find Request Body(Example):
                            
    {
	  "_maCn" : "FindRequest",
	  "clientVersion" : {
	    "major" : 2,
	    "minor" : 8,
	    "patch" : 1
	  },
	  "className": "Account",
	  "fields": "id, strCode, strDescription"
	}
                            
                        
_maCn:     Specifies the request type.

fields:     Specifies the fields that will be returned in search results.

className:     Specifies the Object type to be searched and returned.

Find Response Body (Example):
                                
    {
	  "_maCn" : "FindResponse",
	  "serverVersion" : {
	    "major" : 2,
	    "minor" : 3,
	    "patch" : 1,
	    "preRelease" : "alpha"
	  },
	  "sync" : {
	    "revision" : 0,
	    "needToSync" : false,
	    "dateLastUpdated" : 1560885219000
	  },
	  "objects" : [ {
	    "className" : "Account",
	    "id" : 36380,
	    "strCode" : "102995",
	    "strDescription" : "Inventory : MRO Inventory : MRO Inventory - Spare Parts",
	    "strUniqueKey" : "102995",
	    "new" : false,
	    "uideleted" : false,
	    "dirty" : false
	  } ],
	  "totalObjects" : 1
	}
                                
                          
_maCn:     Specifies the request type.

serverVersion:     Provides information about the server returning the response.

objects:      The result of the search.

totalObjects:      The count of returned object(s) in search result.

Filter Find Request Body(Example):
                            
    {
	  "_maCn" : "FindRequest",
	  "clientVersion" : {
	    "major" : 2,
	    "minor" : 8,
	    "patch" : 1
	  },
	  "className": "Account",
	  "fields": "id, strCode, strDescription",
	  "filters": [{"ql": "id in (?,?)", "parameters" : [36380,36381]}]
	}
                            
                        
_maCn:     Specifies the request type.

fields:     Specifies the fields that will be returned in search results.

filters:     Specifies filter/query instructions along side the required parameter values.

className:     Specifies the Object type to be searched and returned

Filter Find Response Body (Example):
                                
	{
	  "_maCn" : "FindResponse",
	  "serverVersion" : {
	    "major" : 2,
	    "minor" : 3,
	    "patch" : 1,
	    "preRelease" : "alpha"
	  },
	  "sync" : {
	    "revision" : 0,
	    "needToSync" : false,
	    "dateLastUpdated" : 1560885219000
	  },
	  "objects" : [ {
	    "className" : "Account",
	    "id" : 36380,
	    "strCode" : "102995",
	    "strDescription" : "Inventory : MRO Inventory : MRO Inventory - Spare Parts",
	    "strUniqueKey" : "102995",
	    "new" : false,
	    "uideleted" : false,
	    "dirty" : false
	  } ],
	  "totalObjects" : 1
	}
                                
                          
_maCn:     Specifies the request type.

serverVersion:     Provides information about the server returning the response.

objects:      The result of the search.

totalObjects:      The count of object(s) in the search result.

FullText Find Request Body(Example):
                            
	{
	  "_maCn" : "FindRequest",
	  "clientVersion" : {
	    "major" : 2,
	    "minor" : 8,
	    "patch" : 1
	  },
	  "className": "Account",
	  "fields": "id, strCode, strDescription",
	  "filters": [{"fields": "strCode,strDescription", "fullText" : "mro"}]
	}
                            
                        
_maCn:     Specifies the request type.

fields:     Specifies the fields that will be returned in search results.

filters:     Specifies fulltext filter instructions to be used in the query.

filters.fields:     Specifies the comma separated list of fields on which the fulltext query is to be applied.

filters.fullText:     Specifies the fulltext search keyword.

className:     Specifies the Object type to be searched and returned

FullText Find Response Body (Example):
                                
	{
	  "_maCn" : "FindResponse",
	  "serverVersion" : {
	    "major" : 2,
	    "minor" : 3,
	    "patch" : 1,
	    "preRelease" : "alpha"
	  },
	  "sync" : {
	    "revision" : 0,
	    "needToSync" : false,
	    "dateLastUpdated" : 1560885219000
	  },
	  "objects" : [ {
	    "className" : "Account",
	    "id" : 36380,
	    "strCode" : "102995",
	    "strDescription" : "Inventory : MRO Inventory : MRO Inventory - Spare Parts",
	    "strUniqueKey" : "102995",
	    "new" : false,
	    "dirty" : false,
	    "uideleted" : false
	  } ],
	  "totalObjects" : 1
	}
                                
                          
_maCn:     Specifies the request type.

serverVersion:     Provides information about the server returning the response.

objects:      The result of the search.

totalObjects:      The count of object(s) in the search result.

Change Request Body(Example):
                            
    {
	  "_maCn" : "ChangeRequest",
	  "clientVersion" : {
	    "major" : 2,
	    "minor" : 8,
	    "patch" : 1
	  },
	  "className": "Account",
	  "fields": "id, strCode, strDescription",
	  "changeFields": "strCode, strDescription",
	   "object": {
	   		"id":57138,
	        "strCode": "Account2",
	        "strDescription": "Checking Account (edited)",
	        "className": "Account"
	    }
	}
                            
                        
_maCn:     Specifies the request type

fields:     Specifies the fields that will be returned in response results.

changeFields:     Specifies comma separated list of fields to be edited.

className:     Specifies the Object type to be edited.

Change Response Body (Example):
                            
    {
	  "_maCn" : "ChangeResponse",
	  "serverVersion" : {
	    "major" : 2,
	    "minor" : 3,
	    "patch" : 1,
	    "preRelease" : "alpha"
	  },
	  "sync" : {
	    "revision" : 0,
	    "needToSync" : false,
	    "dateLastUpdated" : 1560885219000
	  },
	  "object" : {
	    "className" : "Account",
	    "id" : 57138,
	    "strCode" : "Account2",
	    "strDescription" : "Checking Account (edited)",
	    "strUniqueKey" : "Account2",
	    "new" : false,
	    "uideleted" : false,
	    "dirty" : false
	  },
	  "count" : 1
	}
                               
                          
_maCn:     Specifies the request type.

serverVersion:     Provides information about the server returning the response

object:      Final state of Object that was edited.

count:      The count of edited object(s).

Batch Request Body(Example):
                            
    {
	  "_maCn" : "BatchRequest",
	  "clientVersion" : {
	    "major" : 2,
	    "minor" : 8,
	    "patch" : 1
	  },
	  "requests": [
		{
			"_maCn" : "FindRequest",
			"className": "Account",
			"fields": "id, strCode, strDescription"
		},{
			"_maCn" : "FindRequest",
			"className": "PurchaseOrder",
			"fields": "id, intCode, intPurchaseOrderStatusID, intSupplierID",
			"filters": [{"ql": "intSupplierID > ? and intSupplierID < ?", "parameters" : [259605, 259610]}]
		}
	  ]
	}
                            
                        
_maCn:     Specifies the request type.

requests:     Specifies the set of requests that are to be executed within the batch operation.

fields:     Specifies the fields that will be returned in response results.

filters:     Specifies filter/query instructions along side the required parameter values.

className:     Specifies the Object type to be edited.

Batch Response Body (Example):
                                
    {
	  "_maCn" : "BatchResponse",
	  "serverVersion" : {
	    "major" : 2,
	    "minor" : 3,
	    "patch" : 1,
	    "preRelease" : "alpha"
	  },
	  "sync" : {
	    "revision" : 0,
	    "needToSync" : false,
	    "dateLastUpdated" : 1560885219000
	  },
	  "responses" : [ {
	    "_maCn" : "FindResponse",
	    "objects" : [ {
	      "className" : "Account",
	      "id" : 36380,
	      "strCode" : "102995",
	      "strDescription" : "Inventory : MRO Inventory : MRO Inventory - Spare Parts",
	      "strUniqueKey" : "102995",
	      "new" : false,
	      "uideleted" : false,
	      "dirty" : false
	    }, {
	      "className" : "Account",
	      "id" : 57138,
	      "strCode" : "Account1",
	      "strDescription" : "Checking Account",
	      "strUniqueKey" : "Account1",
	      "new" : false,
	      "uideleted" : false,
	      "dirty" : false
	    } ],
	    "totalObjects" : 2
	  }, {
	    "_maCn" : "FindResponse",
	    "objects" : [ {
	      "className" : "PurchaseOrder",
	      "id" : 184338,
	      "intCode" : 25331,
	      "intPurchaseOrderStatusID" : 104032,
	      "intSupplierID" : 259607,
	      "statusId" : 104032,
	      "new" : false,
	      "uideleted" : false,
	      "dirty" : false
	    },
	    ..
	    ..
	    ..
	    ..
	     {
	      "className" : "PurchaseOrder",
	      "id" : 145385,
	      "intCode" : 21249,
	      "intPurchaseOrderStatusID" : 104032,
	      "intSupplierID" : 259609,
	      "statusId" : 104032,
	      "new" : false,
	      "uideleted" : false,
	      "dirty" : false
	    } ],
	    "totalObjects" : 109
	  } ]
	}
                                
                          
_maCn:     Specifies the request type

responses:     A corresponding set of responses to the set of requests in the batch.

serverVersion:     Provides information about the server returning the response

objects:      The result of the search.

Remove Request Body(Example):
                            
    {
	  "_maCn" : "RemoveRequest",
	  "clientVersion" : {
	    "major" : 2,
	    "minor" : 8,
	    "patch" : 1
	  },
	  "className": "Account",
	   "id":58916
	}
                            
                        
_maCn:     Specifies the request type.

className:     Specifies the Object type to be deleted.

id:     Specifies the id of the Object to be deleted.

Delete Response Body (Example):
                                
    {
	  "_maCn" : "RemoveResponse",
	  "serverVersion" : {
	    "major" : 2,
	    "minor" : 3,
	    "patch" : 1,
	    "preRelease" : "alpha"
	  },
	  "sync" : {
	    "revision" : 0,
	    "needToSync" : false,
	    "dateLastUpdated" : 1560885219000
	  },
	  "count" : 1
	}
                                
                          
_maCn:     Specifies the request type

serverVersion:     Provides information about the server returning the response

count:      Count of deleted object(s).




RPC Example

The following is an example of a request sent to

https://[your subdomain].macmms.com/api/?action=RpcRequest
&service=cmms
&appKey=[your app key]
&accessKey=[your access key]
&signatureMethod=HmacSHA256
&signatureVersion=1


JSON Description
Request Body:
                            
    {
        "_maCn": "RpcRequest",
        "clientVersion": {
            "major": <major_version>,
            "minor": <minor_version>,
            "patch": <patch_version>
        },
        "name": "Ping",
        "action": "Ping"
    }
                            
                        
_maCn:     Specifies the request type

name:     Specifies which RPC object to call

action:     Specifies which method to call

parameters:      Provides the parameters of that said method (not required in this example)

Response Body:
                                
    {
        "_maCn" : "RpcResponse",
        "serverVersion" : {
            ...
            ...
        }
    }
                                
                            
_maCn:     Specifies the request type

serverVersion:     Provides information about the server returning the response

object:     No object is returned by this Ping request

Curl request

                            
    $ curl -d '{"_maCn":"RpcRequest","clientVersion":{"major":[major_version],"minor":[minor_version],"patch":[patch_version]},"name":"Ping","action":"Ping"}' -H "Content-Type: text/plain" -X POST [url]