MosoMRM API


				

				
Contents





  Overview 


The MosoMRM API is implemented and consumed as a RESTful (Representational State Transfer) service. This makes our API different from other SOAP/RPC based APIs that you may be used to invoking. We’ve chosen the RESTful approach to maximize our compatibility with other systems and to minimize the hurdles to interfacing with the API. Before we get into some real life examples that you can experience right now, first we need to cover some basics.


  The Basics 


In order to utilize our API, or to view the associated documentation, you must first be authenticated against one or more MosoMRM instances (why?...See FAQ #1). This means you’ll need the following items before continuing:


  1.  Your MosoMRM site URL e.g. https://demo20.mosocloud.com/.

  2.  A set of credentials consisting of a Username and Password combination.

  3.  An Endpoint Key to identify the terminal from which you are logging-in. (In the MosoMRM User Interface, this is referred to as a “Workstation Id” and it will also display this way on the Log-In screen.



If you do not have all 3 of the items above, please contact your account representative to request a sandbox account.


  Viewing the API Reference Documentation 


Once you have the basic information discussed above, point your web browser to: https://demo20.mosocloud.com/api/1.0/. You will be prompted to Log-In, and after doing so you will be directed to the documentation page. This documentation is generated by our servers in real-time from the current build of the application, ensuring that you are always viewing the most up-to-date version of the documentation.


  Authenticating to the API 


The first step in our journey through the API is to utilize your assigned credentials to authenticate yourself and authorize the API services you will be utilizing. The result of your authentication will be an AuthToken. Once you have a valid AuthToken, you can identify yourself in every subsequent call using only this token, avoiding the need re-send your credentials.


The easiest way to authenticate is to simply Log-In using your browser (see Viewing the API Reference Documentation). Using a browser Log-In will give you access to the API within the context of your current browser window. If you want to Log-In without having to invoke the application UI, you may do so by requesting the following URL (see https://demo20.mosocloud.com/api/1.0/#SessionStart) using your preferred HTTP client (we’ll use CURL for our examples):


  1.  
  2. curl –k “[https://demo20.mosocloud.com/api/1.0/session/?username={USERNAME}&password={PASSWORD}&endpointkey={ENDPOINTKEY}]"
  3.  







If successful, the response will appear with the following structure:


  1.  
  2. JSON
  3.  
  4. {
  5.   "Result": {
  6.     "Control": {
  7.       "ErrorCode": 0,
  8.       "Message": "SUCCESS"
  9.     },
  10.     "Data": {
  11.       "String": "5afe51b6-2fca-4a68-90ed-cc11ed415a4d"
  12.     }
  13.   }
  14. }
  15.  


  1.  
  2. XML
  3.  
  4. <Result>
  5.   <Control>
  6.     <ErrorCode>0</ErrorCode>
  7.     <Message>SUCCESS</Message>
  8.   </Control>
  9.   <Data>
  10.     <String>8fd9d213-c5e4-4664-b495-d93845a87afa</String>
  11.   </Data>
  12. </Result>
  13.  




Let’s take a moment to dissect the data we just received. You’ll notice that there are two formats, JSON and XML. You may choose to utilize either format when interfacing with the API, and while it is perfectly valid to switch formats between each request, you should note that every request/response pair will be read and sent back to you in the same format. To choose the format you want to work with, you must include a Content Type header in your request packet. 



  •  To use XML, set the Content Type to “text/xml”.

  •  To use JSON use “application/json”. The default format will always be JSON when no Content Type is specified.



The structure of the response will be consistent for every API service and consists of a Result root node, a Control child node, and a Data child node.



  •  The Control node contains an ErrorCode and a Message node. 

  •  The Data node will contain various other entities ranging from primitive types, like the AuthToken, to complex data types with multiple descendants and other types.



  Success and Failure Codes 


If all goes well with your API call, the response will contain an ErrorCode of “0”. In this case, the "Message” will also always be “SUCCESS”. If an error occurs, the ErrorCode will be an HTTP status code, most likely "500" (application error), and the error message will contain information related to the error.


  Requesting Information Using the API 


When you use the API to retrieve information, this is called a “GET” request in HTTP parlance. This is the easiest method to use when calling our API making it perfect for our first example:


Let’s "get" a list of Business Units (https://demo20.mosocloud.com/api/1.0/#BusinessUnitsGet).


Request:


  1.  
  2. curl –k “https://demo20.mosocloud.com/api/1.0/businessunits/?authtoken={AuthToken}”
  3.  


  • Note: If your HTTP client can accept cookies, you wont have to specify the "AuthToken" param in the request.



To retrieve a single Business Unit, the request would simply specify the id:



  1.  
  2. curl –k “https://demo20.mosocloud.com/api/1.0/businessunits/1
  3.  


Response:


  1.  
  2. {
  3.   "Result": {
  4.     "Control": {
  5.       "ErrorCode": 0,
  6.       "Message": "SUCCESS"
  7.     },
  8.     "Data": {
  9.       "BusinessUnit": {
  10.         "TimeZoneName": "US/Eastern",
  11.         "BatchMerchantAccountCode": 2001,
  12.         "DivisionId": 2,
  13.         "Name": "Silver Spring",
  14.         "Code": "100",
  15.         "Description": "",
  16.         "Sequence": 0,
  17.         "InActive": false,
  18.         "GLCodePrefix": "100",
  19.         "PermissionInherited": false,
  20.         "PrimaryContactInfo": {
  21.           "BusinessUnitId": 0,
  22.           "ContactInformationType": 0,
  23.           "Address1": null,
  24.           "Address2": null,
  25.           "Address3": null,
  26.           "City": null,
  27.           "StateProvinceId": null,
  28.           "PostalCode": null,
  29.           "CountryId": null,
  30.           "PhoneNumber1CountryCode": null,
  31.           "PhoneNumber1": null,
  32.           "PhoneNumber1DialingInfo": null,
  33.           "PhoneNumber2CountryCode": null,
  34.           "PhoneNumber2": null,
  35.           "PhoneNumber2DialingInfo": null,
  36.           "FaxNumberCountryCode": null,
  37.           "FaxNumber": null,
  38.           "FaxNumberDialingInfo": null,
  39.           "EmailAddress": null,
  40.           "WebsiteUrl": null,
  41.           "AggregateResourceName": 154,
  42.           "ObjectId": "00000000-0000-0000-0000-000000000000",
  43.           "ResourceHandle": null,
  44.           "ID": 0,
  45.           "HasSecurityContext": false,
  46.           "SecurityContext": null
  47.         },
  48.         "ObjectId": "cada8073-c26a-4524-b62f-cadba670b415",
  49.         "ID": 1,
  50.         .
  51.         .
  52.         .
  53.  


  Frequently Asked Questions 


Why must I be logged in to view the API documentation?



  •  Just like the application itself, our API is tailored for the individual user. This means that different users will be able to see and access different parts of the API. That’s why we need to know who you are before you can interface with the API.



  Related Information 








Retrieved from "http://wiki.mosocloud.com/MosoMRM_API"

				
								

				


				

				
				

					  
																										What Links Here
						|
																 This page was last modified on 30 July 2014, at 14:00.
						|