SmartObject OData API

The SmartObject OData API lets you retrieve SmartObject data through the K2 OData feed in JSON format. Before you can use this API, you will need to enable the SmartObject OData services in the K2 Management site. Please refer to the following topics in the User Guide for more information:

You should also pay attention to the considerations for using the SmartObject OData API.

For sample code that illustrates how to interact with these APIs, please see C# and javascript. These samples use Basic authorization, but you can also use OAuth by setting the header up correctly and confirming that AAD Consent has been granted.

Using OAuth instead of Basic Authentication

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

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 AAD 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)

//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 Azure Active Directory 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 K2 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.