SmartObject OData API

The SmartObject OData API lets you retrieve and interact with SmartObject data through the K2 OData feed in JSON format. The SmartObject OData v3 API supports a single List method.

 Before you can use this API, enable it in the Management site. See the following topics in the User Guide for more information:

Pay attention to the considerations for using the SmartObject OData API.

For sample code that illustrates how to interact with the OData v3 API, see the topics Using the SmartObject OData v3 API in C# and Using the SmartObject OData v3 API in JavaScript. These samples use Basic authorization, but you can also use OAuth by setting the header up correctly and confirming that Azure Active Directory Consent has been granted.

See the KB Article KB002784: Configure Azure Active Directory and K2 Services for Inbound OAuth for information on setting up OAuth with an Azure Active Directory App.

The following code snippet shows how to get an OAuth token in C#, where the user gets prompted to login through the Azure Active Directory Sign-on page if a token isn't found.

Copy

Getting an OAuth token

Uri _baseUrl = new Uri("https://[environmentid]/api"); //TODO: replace with your K2 environment's URL
string _clientId = "3cb1141a-a226-497d-a512-8a4a2e512aec"; //Application ID of the client requesting the token (K2 API app, in this case)
string _authority = "https://login.microsoftonline.com/common/login"; //Login URL for <span class="mc-variable BrandingThirdParty.Azure_Active_Directory variable">Azure Active Directory</span> Instance
string _redirectUri = @"https://api.k2.com/client"; //Address to return to upon receiving a response from the authority
string _webApiResourceId = @"https://api.k2.com/"; //Identifier of the target resource that is the recipient of the requested token
string _resource = "/odata/v3/"; //the endpoint you want to query (in this case, all SmartObjects that have at least one list method are returned)
//string _resource = "/odatav4/v4/"; // this is the OData v4 endpoint

//set up http client
System.Net.Http.HttpClient _httpClient = new HttpClient(new HttpClientHandler()
{
    UseDefaultCredentials = false,
});

//platform specific arguments and information
Microsoft.IdentityModel.Clients.ActiveDirectory.PlatformParameters parameters = new PlatformParameters(PromptBehavior.Auto);
//retrieves authentication tokens from <span class="mc-variable BrandingThirdParty.Azure_Active_Directory variable">Azure Active Directory</span> and ADFS services
Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext authContext = new AuthenticationContext(_authority);
Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationResult authResult = null;

try {
 //get the OAuth token (will show login screen to user if no token found)
 authResult = authContext.AcquireTokenAsync(_webApiResourceId, _clientId, new Uri(_redirectUri), parameters).Result;
} catch (Microsoft.IdentityModel.Clients.ActiveDirectory.AdalException adalEx) {
 //TODO: do something with the auth error
 return;
}

//use pathos client to construct the HTTP request and read response
Pathoschild.Http.Client.IRequest request = null;
Pathoschild.Http.Client.IResponse result = null;

request = (Pathoschild.Http.Client.IRequest) new Pathoschild.Http.Client.FluentClient(_baseUrl, _httpClient).GetAsync(_resource).WithHttpErrorAsException(false);
//pass in the access token that was obtained
request = request.WithBearerAuthentication(authResult.AccessToken);
result = request.AsResponse().Result;
//get the result form the endpoint call
string returnvalue = result.Message.Content.ReadAsStringAsync().Result;

Tips

  • Use the Management interface to refresh the OData service. You can also refresh the K2 OData service in code by calling the following endpoint: https://[k2_site_name]/api/odata/op/refresh
  • To see which SmartObjects are exposed via the OData API, just pass in the base URL to your OData feed in your code, for example https://[K2site]/api/odata/v3.
  • The endpoint is based the SmartObject System Name, not the SmartObject's Display Name.