Creating a Web API
In iCore Integration Suite, a Web API is a program written in C# based on ASP.NET Core. Web APIs are created and edited in the Web API Editor. The API is saved as a Web API definition entity.
note
This help file does not provide any general information about writing programs in C#, or how to use ASP.NET Core. For more information about ASP.NET Core, refer to the official Microsoft documentation at https://docs.microsoft.com/en-us/aspnet/core. For which specific version is used see Software dependencies.
When you create a Web API in iCIS, you have access to NSwag which can be used to publish Swagger 2.0 and OpenAPI 3.0 specifications automatically from your Web API. For more information and documentation about NSwag, see the official homepage at http://nswag.org/. For which specific version is used see Software dependencies.
Web API documentation
Web APIs in iCore support XML documentation, which makes it possible to add XML documentation above any definition in a Web API. The documentation will appear as notes when viewing the Web API in the Swagger UI.
For more information about XML documentation in NSwag, see the official homepage (link above). For information about general guidelines for XML documentation, refer to the Microsoft documentation at https://docs.microsoft.com/en-us/dotnet/csharp/codedoc.
Examples
This example shows how you can add a summary comment on a method in a controller class:
///<summary>
///Get status of specific order.
///</summary>
[HttpGet("order/status/{transactionId}")]
[SwaggerResponse(typeof(OrderStatus))]
public IActionResult GetOrderStatus(long transactionId)
{
INode node;
try
{
node = SystemContext.Nodes.Get(transactionId);
}
catch (EntityNotFoundException ex)
{
return NotFound(ex.Message);
}
string orderStatus = node.GetAttributeValue<string>(StartupArguments.OrderStatusNodeAttributeId);
return Json(new OrderStatus { Status = orderStatus });
}
To add XML documentation on the return type from the example method above, use the following code:
///<summary>
///The current status of an order.
///</summary>
public class OrderStatus
{
///<summary>The status of an order</summary>
public string Status { get; set; }
///<summary>
///Last modified date of order
///</summary>
public DateTime LastModified { get; set;}
}