If using a .NET language, it is recommended to use the Momentus Enterprise SDK. Momentus provides you with the package Ungerboeck.Api.Sdk on NuGet, which is a complete API client with pre-made API calls, options and models with pre-made properties that represent the various subjects in the software. You can include it as a reference in your project and take advantage of the objects. Essentially, most of the API coding work is done for you.
There are many benefits to using the SDK, including:
- Less coding for you.
- When you upgrade software versions and the SDK, the SDK also gets new models and wrapper functions with the new SDK version.
- Token management. Set how the JWT is generated and the client maintains it from there.
- Easy options to control validations and searching in API calls.
Install the SDK
You can find the SDK on the NuGet. If you only want the collection of subject models and properties, that is available as well, though the SDK is the full package to start a project. You can install either of these directly into your .NET project using the Visual Studio Package Manager or NuGet commands.
Make sure the second value in the SDK package version matches your software version. Momentus always recommends the latest package version within your software version. See below for an example match.
Example Project
You can also find an example project on GitHub. This shows you all the various ways to use the API via code. Select your software version to find the correct project and get started with looking through examples!
The code with and without wrappers is shown below.
Make Your First Call
To use the API, you need to first generate a JWT using your API User information. See API Users for details on creating API users. After you create an API user, you need the API User ID, secret and a key from its list of API User Keys.
To get that token, you generate locally using JWT libraries.
With the SDK
Retrieve a Token
Below is an example call to retrieve the token and a sample response.
var auth = GetApiClientAuth();
var apiClient = new Ungerboeck.Api.Sdk.ApiClient(auth);
private static void GetApiClientInfoAuth()
{
return new Ungerboeck.Api.Models.Authorization.Jwt()
{
APIUserID = “MYUSERID”
Key = “GET-THIS-GUID-FROM-API-USERS-WINDOW”
Secret = “GET-THIS-GUID-FROM-API-USERS-WINDOW”
UngerboeckURI =“http://mydomain.ungerboeck.net/test“,
Expiration = System.DateTime.Now.AddMinutes(1) //Instead of a static DateTime, you can set the AutoRefresh ability (see below)
};
}
Your API client is now ready to make calls.
Search Request
This example shows how to find all events matching a certain description.
SearchResponse<EventsModel> myEventResults = apiClient.Endpoints.Events.Search(orgCode, $"{nameof(EventsModel.Description)} eq '{searchValue}'");
Without the SDK
Create JWT
First, you must generate a JWT. You can use the list of suggested libraries found on jwt.io for your language. If you use Javascript, here is a Javascript example to follow.
Once you have your JWT, you want to retain that in memory.
Retrieve an Account
Now that you have the token (JWT), you can make a call to the API, such as GET, POST, PUT, and DELETE.
Try a GET to retrieve an account.
Request (in C#):
Use HttpClient for the http connection. Start by adding the package for Microsoft.AspNet.WebApi.Client. Then add the code:
using System.Net.Http.Headers;
...
string url = "https://YourSite.ungerboeck.net/api/v1/Accounts/10/ACCTCODE"; //Replace ACCTCODE with an account code from your Ungerboeck. This also assumes organization code 10.
using (var client = new HttpClient())
{
using (var requestMessage = new HttpRequestMessage(HttpMethod.Get, url))
{
requestMessage.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "qyJhb4ciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJKV0VMTEVTIiwia2V5IjoiOWFjN2Y2MzItMjcyNC00MDk4LTgyYjktMzhiYjg5YzcyNDdlIiwiZXhwIjoiMTY0MjQ0MDgxNCIsImlhdCI6IjE2NDI0NDA3NTQiLCJzdWIiOiIifQ.b8xeIbDABNbhdLC8TFHXUN1GEBA54ZjorNN3VTdi9rQ");
requestMessage.Headers.Add("Accept", "application/json");
var response = await client.SendAsync(requestMessage).ConfigureAwait(false);
string account = await response.Content.ReadAsStringAsync();
}
}
You can see that the token is passed as an HTTP Header inside the request. Do this for all calls to the API.
Your response content body appears as a JSON object representing the output from your call. In this case, the output is a single account like this:
[
{
"Organization": "10",
"AccountCode": "0002225",
"MiddleInitial": "",
"FirstName": "",
"LastName": "",
"Name": " ",
"Search": "",
"Salutation": "",
"Title": "",
"Address1": "",
"Address2": "",
"Address3": "",
"Address4": "",
"Address5": "",
"Address6": "",
"City": "",
"State": "",
"PostalCode": "",
"Country": "",
"Region": "",
"Keyword": "",
"Keyword2": "",
"LegalName": "",
"Nickname": "",
"Class": "O",
"Phone": null,
"Fax": null,
"Mobile": null,
"Direct": null,
"MarketSegmentMajor": "",
"MarketSegmentMinor": "",
"Email": null,
"Website": null,
"Company": "",
...}
Now you have completed the cycle of setting up an API call.
Comments
3 comments
Rudy Scoggins is there a mechanism to increase the timeout for the new SDK ApiClient?
With the old one I think we were able to pass in a HttpClient so had more control, but I can't see if/how this is now possible?
We have a report we're running which takes a little longer to run, so want to allow for this.
Thanks!
0 upvotes
Hi Lee,
That might be a good thing to expose. I'll get it going.
Out of curiosity, how long does the report take to run?
Rudy
0 upvotes
Super thanks- we could provide the HttpClient with the old SDK.
I think the report SQL takes about a minute, but the render/export seems to take an additional minute,. So roughly 2 minutes in total.
1 upvotes
Please sign in to leave a comment.