Home Developer Guide Rest API

Rest API

1. AuthToken

  • URL: “/RestApi/AuthToken? Username=<username>&password=<password>”
  • Method: GET
  • URL Params:
    • username [string] [Required]=the username of Cirrus Shield user
    • password [string] [Required]= the password of Cirrus Shield user
  • Success Response:
    • Status Code=200 (OK)
    • Returned Data [string]= the authentication token
  • Error Response:
    • Status Code=404 (Not Found) (in case the user was not found)

 

2. Describe

  • URL: « /RestApi/Describe/<objectName>?authToken=<authToken> »
  • Method: GET
  • URL Params:
    • objectName [string] [Required]=the name of the object that the user wants to describe
    • authToken [string] [Required]=the authentication token
  • Success Response:
    • Status Code=200 (OK)
    • Returned Data [in XML or JSON]=a detailed description of the object (name, label, plural label, fields, …)
  • Error Response:
      • Status Code=401 (Unauthorized) (in case of a wrong authentication token)

    Or

    • Status Code=400 (BadRequest) (in case of an empty object name parameter)

 Example of returned data (in xml format) (objectName=”Account”):

<?xml version="1.0"?>

<ObjectDescriptor>



  <APIName>Account</APIName>

  <Fields>


<FieldDescriptor>



<ClrValIfLkUpDel>false</ClrValIfLkUpDel>

<DataType>Text</DataType>

<DecimalPlaces i:nil="true"/>

<DefaultValue/>

<DisplayFormat/>

<IsAlphabeticallySorted>false</IsAlphabeticallySorted>

<IsCaseSensitive>false</IsCaseSensitive>

<IsCustom>false</IsCustom>

<IsDeletable>false</IsDeletable>

<IsEditable>false</IsEditable>

<IsRequired>true</IsRequired>

<IsUnique>true</IsUnique>

<Label>Id</Label>

<Length i:nil="true"/>
<Name>Id</Name>

<PicklistValues i:nil="true"/>

<Prefix/>

<RelatedToObject i:nil="true"/>

<RelationshipName/>

<StartingNumber i:nil="true"/>

<Suffix/>

<VisibleLinesNb i:nil="true"/>


</FieldDescriptor>

<FieldDescriptor>



<ClrValIfLkUpDel>false</ClrValIfLkUpDel>

<DataType>Text</DataType>

<DecimalPlaces i:nil="true"/>

<DefaultValue/>

<DisplayFormat/>

<IsAlphabeticallySorted>false</IsAlphabeticallySorted>

<IsCaseSensitive>false</IsCaseSensitive>

<IsCustom>false</IsCustom>

<IsDeletable>false</IsDeletable>

<IsEditable>true</IsEditable>

<IsRequired>true</IsRequired>

<IsUnique>false</IsUnique>

<Label>Name</Label>

<Length i:nil="true"/>

<Name>Name</Name>

<PicklistValues i:nil="true"/>

<Prefix/>

<RelatedToObject i:nil="true"/>

<RelationshipName/>

<StartingNumber i:nil="true"/>

<Suffix/>

<VisibleLinesNb i:nil="true"/>


</FieldDescriptor>

<FieldDescriptor>



<ClrValIfLkUpDel>false</ClrValIfLkUpDel>

<DataType>LookupRelationship</DataType>

<DecimalPlaces i:nil="true"/>

<DefaultValue/>

<DisplayFormat/>

<IsAlphabeticallySorted>false</IsAlphabeticallySorted>

<IsCaseSensitive>false</IsCaseSensitive>

<IsCustom>false</IsCustom>

<IsDeletable>false</IsDeletable>

<IsEditable>true</IsEditable>

<IsRequired>true</IsRequired>

<IsUnique>false</IsUnique>

<Label>Owner</Label>

<Length i:nil="true"/>

<Name>OwnerId</Name>

<PicklistValues i:nil="true"/>

 <Prefix/>

<RelatedToObject i:nil="true"/>

<RelationshipName>Account1</RelationshipName>

<StartingNumber i:nil="true"/>

<Suffix/>

<VisibleLinesNb i:nil="true"/>


</FieldDescriptor>

<FieldDescriptor>



<ClrValIfLkUpDel>false</ClrValIfLkUpDel>

<DataType>LookupRelationship</DataType>

<DecimalPlaces i:nil="true"/>

<DefaultValue/>

<DisplayFormat/>

<IsAlphabeticallySorted>false</IsAlphabeticallySorted>

<IsCaseSensitive>false</IsCaseSensitive>

<IsCustom>false</IsCustom>

<IsDeletable>false</IsDeletable>

<IsEditable>false</IsEditable>

<IsRequired>true</IsRequired>

<IsUnique>false</IsUnique>

<Label>Created By</Label>

<Length i:nil="true"/>

<Name>CreatedById</Name>

<PicklistValues i:nil="true"/>

<Prefix/>

<RelatedToObject i:nil="true"/>

<RelationshipName>Account2</RelationshipName>

<StartingNumber i:nil="true"/>

<Suffix/>

<VisibleLinesNb i:nil="true"/>


</FieldDescriptor>

<FieldDescriptor>



<ClrValIfLkUpDel>false</ClrValIfLkUpDel>

<DataType>DateTime</DataType>

<DecimalPlaces i:nil="true"/>

<DefaultValue/>

<DisplayFormat/>

<IsAlphabeticallySorted>false</IsAlphabeticallySorted>

<IsCaseSensitive>false</IsCaseSensitive>

<IsCustom>false</IsCustom>

<IsDeletable>false</IsDeletable>

<IsEditable>false</IsEditable>

<IsRequired>true</IsRequired>

<IsUnique>false</IsUnique>

<Label>Creation Date</Label>

<Length i:nil="true"/>

<Name>CreationDate</Name>

<PicklistValues i:nil="true"/>

<Prefix/>

<RelatedToObject i:nil="true"/>

<RelationshipName/>

<StartingNumber i:nil="true"/>

<Suffix/>

<VisibleLinesNb i:nil="true"/>


</FieldDescriptor>

<FieldDescriptor>



<ClrValIfLkUpDel>false</ClrValIfLkUpDel>

<DataType>LookupRelationship</DataType>

<DecimalPlaces i:nil="true"/>

<DefaultValue/>

<DisplayFormat/>

<IsAlphabeticallySorted>false</IsAlphabeticallySorted>

<IsCaseSensitive>false</IsCaseSensitive>

<IsCustom>false</IsCustom>

<IsDeletable>false</IsDeletable>

<IsEditable>false</IsEditable>

<IsRequired>true</IsRequired>

<IsUnique>false</IsUnique>

<Label>Modified By</Label>

<Length i:nil="true"/>

<Name>ModifiedById</Name>

<PicklistValues i:nil="true"/>

<Prefix/>

<RelatedToObject i:nil="true"/>

<RelationshipName>Account3</RelationshipName>

<StartingNumber i:nil="true"/>

<Suffix/>

<VisibleLinesNb i:nil="true"/>


</FieldDescriptor>

<FieldDescriptor>



<ClrValIfLkUpDel>false</ClrValIfLkUpDel>

<DataType>DateTime</DataType>

<DecimalPlaces i:nil="true"/>

<DefaultValue/>
<DisplayFormat/>

<IsAlphabeticallySorted>false</IsAlphabeticallySorted>

<IsCaseSensitive>false</IsCaseSensitive>

<IsCustom>false</IsCustom>

<IsDeletable>false</IsDeletable>

<IsEditable>false</IsEditable>

<IsRequired>true</IsRequired>

<IsUnique>false</IsUnique>

<Label>Modification Date</Label>

<Length i:nil="true"/>

<Name>ModificationDate</Name>

<PicklistValues i:nil="true"/>

<Prefix/>

<RelatedToObject i:nil="true"/>

<RelationshipName/>

<StartingNumber i:nil="true"/>

<Suffix/>

<VisibleLinesNb i:nil="true"/>


</FieldDescriptor>

<FieldDescriptor>



<ClrValIfLkUpDel>false</ClrValIfLkUpDel>

<DataType>Checkbox</DataType>

<DecimalPlaces i:nil="true"/>

<DefaultValue/>

<DisplayFormat/>

<IsAlphabeticallySorted>false</IsAlphabeticallySorted>

<IsCaseSensitive>false</IsCaseSensitive>

<IsCustom>false</IsCustom>

<IsDeletable>false</IsDeletable>

<IsEditable>false</IsEditable>

<IsRequired>true</IsRequired>

<IsUnique>false</IsUnique>

<Label>Is Deleted</Label>

<Length i:nil="true"/>

<Name>IsDeleted</Name>

<PicklistValues i:nil="true"/>

<Prefix/>

<RelatedToObject i:nil="true"/>

<RelationshipName/>

<StartingNumber i:nil="true"/>

<Suffix/>

<VisibleLinesNb i:nil="true"/>


</FieldDescriptor>



</Fields>

<Icon/>

<IsCustom>true</IsCustom>

<IsDeletable>true</IsDeletable>

<IsEditable>true</IsEditable>

<Label>Account</Label>

<PluralLabel>Accounts</PluralLabel>



</ObjectDescriptor>

 

 

3. Describe All

  • URL: « /RestApi/DescribeAll?authToken=<authToken> »
  • Method: GET
  • URL Params:
    • authToken [string] [Required]=the authentication token
  • Success Response:
    • Status Code=200 (OK)
    • Returned Data [in XML or JSON]=a list of all the objects of the user organization
  • Error Response:
    • Status Code=401 (Unauthorized) (in case of a wrong authentication token)

 

Example of returned data (in xml format):


<?xml version="1.0"?>

<ArrayOfObjectDescriptor>



<ObjectDescriptor>



<APIName>Organization</APIName>

<Fields i:nil="true"/>
<Icon/>

<IsCustom>false</IsCustom>

<IsDeletable>false</IsDeletable>

<IsEditable>true</IsEditable>

<Label>Organization</Label>

<PluralLabel>Organizations</PluralLabel>



</ObjectDescriptor>

<ObjectDescriptor>



<APIName>UserPosition</APIName>

<Fields i:nil="true"/>

<Icon/>

<IsCustom>false</IsCustom>

<IsDeletable>false</IsDeletable>

<IsEditable>false</IsEditable>

<Label>Position</Label>

<PluralLabel>Positions</PluralLabel>



</ObjectDescriptor>

<ObjectDescriptor>



<APIName>Profile</APIName>

<Fields i:nil="true"/>

<Icon/>

<IsCustom>false</IsCustom>

<IsDeletable>false</IsDeletable>

<IsEditable>false</IsEditable>

<Label>Profile</Label>

<PluralLabel>Profiles</PluralLabel>



</ObjectDescriptor>

<ObjectDescriptor>



<APIName>License</APIName>

<Fields i:nil="true"/>

<Icon/>

<IsCustom>false</IsCustom>

<IsDeletable>true</IsDeletable>

<IsEditable>true</IsEditable>

<Label>License</Label>

<PluralLabel>Licenses</PluralLabel>



</ObjectDescriptor>

<ObjectDescriptor>



<APIName>LoginHistory</APIName>

<Fields i:nil="true"/>

<Icon/>

<IsCustom>false</IsCustom>

<IsDeletable>false</IsDeletable>

<IsEditable>false</IsEditable>

<Label>Login History</Label>

<PluralLabel>Login History</PluralLabel>



</ObjectDescriptor>

<ObjectDescriptor>



<APIName>Account</APIName>

<Fields i:nil="true"/>

<Icon/>

<IsCustom>true</IsCustom>

<IsDeletable>true</IsDeletable>

<IsEditable>true</IsEditable>

<Label>Account</Label>

<PluralLabel>Accounts</PluralLabel>



</ObjectDescriptor>



</ArrayOfObjectDescriptor>


 

4. Query

  • URL: « /RestApi/Query?authToken=<authToken>&selectQuery=<selectQuery> »
  • Method: GET
  • URL Params:
    • authToken [string] [Required]=the authentication token
    • selectQuery [string] [Required]=the select query. Example: “SELECT Name FROM Account WHERE Id=1329023730348722379”.
  • Success Response:
    • Status Code=200 (OK)
    • Returned Data [in XML or JSON]=a list of the selected records

 

Example of returned data (in xml format):


 <Data>



<Account>



<Name>

Account Test 1

</Name>

<Address>

Address Test 1

</Address>



</Account>

<Account>



<Name>

Account Test 2

</Name>

<Address>

Address Test 2

</Address>



</Account>



 </Data>
  • Error Response:
    • Status Code=401 (Unauthorized) (in case of a wrong authentication token)
    • Or
    • Status Code=400 (BadRequest) (in case the “querying data” operation was unsuccessful)

 

 

5. Data Action

  • URL: « /RestApi/DataAction/<objectName>?authToken=<authToken>&action=<action>&matchingFieldName=<matchingFieldName> »
  • Method: POST
  • URL Params:
    • objectName [string] [Required]=the name of the object that the user wants to insert/update/upsert/delete records from
    • authToken [string] [Required]=the authentication token
    • action [string] [Required]=the action that the user wants to apply (insert, update, upsert or delete)
    • matchingFieldName [string] [Required]=the name of the field that is considered to be the unique field in the sent records
  • Data Params:
    • xmlData [XML]=the data records to insert/update/upsert/delete

Example:

<Data>


<Account>


<Name>

Account Test 1

</Name>

<Address>

Address Test 1

</Address>


</Account>

<Account>


<Name>

Account Test 2

</Name>

<Address>

Address Test 2

</Address>


</Account>


</Data>

 

When sending data parameters from a php page and having a field of type « Datetime », we must put this function urlencode() in order not to lose the “+” sign on the server side and to be saved correctly in the database.

If the function is not used, the value will saved without the “+” sign like this “2017-06-12 15:40: 47 02 ” instead of “2017-06-12 15:40: 47+02 “.

Example of using urlencode() :

$ xmlData =  urlencode (


"<Data>"

"<Campaign>"

"<Name> Campagne-". $ CampaignID. "</Name>"

"<Campaign_ID>". $ CampaignID. "</Campaign_ID>"

"<TestDateTime>"2017-06-12 15: 40: 47 + 02"."</TestDateTime>"

"<OwnerId>".$ OwnerID. "</OwnerId>"


"<Campaign>"


"<Data>"


);

  • Success Response:
    • Status Code=200 (OK)
    • Returned Data [in XML or JSON]=a list of the data records sent in the HTTP Post Request body with 2 additional fields for each record (1- Success (to indicate if the operation (insert/update/upsert/delete) applied on the corresponding record was successful or not), 2- ErrorMessage (to indicate what is the error that caused the operation applied on this record to fail (in case of unsuccessful operation)))

Example of returned data:

<Data>


<Account>


<Name>

Account Test 1

</Name>

<Address>

Address Test 1

</Address>

<Success>

FALSE

</Success>

<ErrorMessage>

Some of the Lookup Fields contain invalid values

</ErrorMessage>


</Account>

<Account>


<Name>

Account Test 2

</Name>

<Address>

Address Test 2

</Address>

<Success >

TRUE

</Success>

<ErrorMessage />


</Account>


</Data>
  • Error Response:
    • Status Code=401 (Unauthorized) (in case of a wrong authentication token)
    • Or
    • Status Code=400 (BadRequest) (in case no object name was specified or no action was specified or there is an error in the xml data records sent in the HTTP Post Request body or if one record or more could not be inserted/updated/upserted/deleted)

 

6. Upload File

  • URL: « /RestApi/UploadFile»
  • Method: POST
  • URL Params:
    • authToken [string] [Required]=the authentication token
    • fileName [string] [Required]=the name of the file that the user wants to upload
    • objectName [string] [Required]=the name of the record’s object that the user wants to upload the file to
    • fieldName [string] [Required]=the API name of the field that the file will be uploaded to
    • RecGUID [long] [Required]=the record Id in CirrusShield that the file will be uploaded to
  • Data Params:
    • dataStream =the data of the uploaded file

Example:

// Get file name

$fileName = $_FILES['file_upl']['name'];


// Get file content

$data = file_get_contents($_FILES['file_upl']['tmp_name']);


// Transform file content to json array

$array = array();

foreach(str_split($data) as $char){


array_push($array, ord($char));


}


// Send the Data Params

curl_setopt($client, CURLOPT_POSTFIELDS, "=".json_encode($array));


<form name="file_up" action="UploadFile.php" method="POST" enctype="multipart/form-data">


Upload your file here

<input type="file" name="file_upl" id="file_upl"/>

<input type="submit" name="action" value="submit"/>


</form>
  • Success Response :
    • Status Code=200 (OK)
  • Error Response:
    • Status Code=400 (BadRequest) (in case there is an error in the json data sent in the HTTP Post Request body or if the object name, API field name in the object or record id are wrong)

 

 

Articles

Was this article helpful to you? Yes No

How can we help?