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. The SmartObject OData v4 API supports all SmartObject methods.
Before you can use this API, enable it in the K2 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
For examples of OData v4 endpoints see the topic SmartObject OData API v4 endpoints and for sample code that illustrates how to interact with the OData v4 API, see the topic Using the SmartObject OData API v4 in C#.
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.
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 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)
//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 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.