Skyline.DataMiner.Utils.UserDefinedApiToolkit 10.6.8.7

Skyline.DataMiner.Utils.UserDefinedApiToolkit

About

Quickly build REST APIs in DataMiner using an attribute/controller-based approach similar to ASP.NET Core. This package builds upon the User-Defined API actions available in DataMiner and makes them easier to use, providing attribute routing, dependency injection, typed results, and automatic OpenAPI specification generation.

using Microsoft.Extensions.DependencyInjection;

using Skyline.DataMiner.Automation;
using Skyline.DataMiner.Net.Apps.UserDefinableApis.Actions;
using Skyline.DataMiner.Utils.UserDefinedApiToolkit;

/// <summary>
///     DataMiner Script Class.
/// </summary>
public static class Script
{
	// Build the API once and cache it; AddControllers() scans the calling assembly and
	// registers every public ControllerBase implementation decorated with [Route].
	private static Lazy<IUserDefinedApi> _api = new Lazy<IUserDefinedApi>(() => UserDefinedApi.CreateBuilder()
		.AddControllers()
		.ConfigureServices(services => services.AddScoped<IUserRepository, UserRepository>())
		.Build());

	/// <summary>
	///     The Script entry point.
	/// </summary>
	/// <param name="engine">Link with SLAutomation process.</param>
	/// <param name="requestData">The incoming API request.</param>
	[AutomationEntryPoint(AutomationEntryPointType.Types.OnApiTrigger)]
	public static ApiTriggerOutput OnApiTrigger(IEngine engine, ApiTriggerInput requestData)
	{
		return _api.Value.Run(engine, requestData);
	}
}

// You can define your endpoints by inheriting from the ControllerBase class
[ApiController]
[Route("v1/users")]
public class UsersController : ControllerBase
{
	private readonly IUserRepository _repository;

	public UsersController(IUserRepository repository)
	{
		_repository = repository;
	}

	[HttpGet]
	[Produces("application/json")]
	public ApiResult<List<UserDto>, string> GetAll([FromQuery] int page = 1, [FromQuery] int pageSize = 10)
	{
		var users = _repository.GetAll(page, pageSize);
		return Ok(users);
	}

	[HttpGet("{id}")]
	[Produces("application/json")]
	public ApiResult<UserDto, string> GetById(int id)
	{
		var user = _repository.GetById(id);
		return user is null ? NotFound("User not found.") : Ok(user);
	}

	[HttpPost]
	[Consumes("application/json")]
	public ApiResult<UserDto, string> Create([FromBody] UserDto dto)
	{
		_repository.Create(dto);
		return Created(dto);
	}
}

If you have questions, you can post them to our DataMiner community platform.

Installation

dotnet add package Skyline.DataMiner.Utils.UserDefinedApiToolkit

Features

Generating an OpenAPI specification

Add the following to your API project's .csproj to generate an openapi.json (or .yaml) file in your build output whenever you build:

<PropertyGroup>
  <GenerateOpenApi>True</GenerateOpenApi>
  <OpenApiFormat>json</OpenApiFormat> 
  <OpenApiInfoTitle>Sample User API</OpenApiInfoTitle> 
  <OpenApiInfoVersion>1.0.0</OpenApiInfoVersion> 
  <OpenApiInfoDescription>This is a **global description** of the API.</OpenApiInfoDescription> 
</PropertyGroup>

The generated document includes every controller's routes, HTTP methods, request/response schemas, and (when GenerateDocumentationFile is enabled) the XML doc comments on your actions.

Path variables

Route templates support ASP.NET-Core-style {placeholder} segments on the [HttpGet]/[HttpPost]/ [HttpPut]/[HttpDelete] attributes. The method-level template is appended to the controller's [Route] template to form the full route (e.g. "v1/items" + "{id}" → "v1/items/{id}").

A parameter binds from a placeholder either implicitly (its name matches the placeholder) or explicitly via [FromRoute] (with an optional Name override when the C# parameter name differs from the placeholder name):

[ApiController]
[Route("v1/items")]
public class ItemsController : ControllerBase
{
	// Implicit binding: the "id" parameter name matches the "{id}" placeholder.
	[HttpGet("{id}")]
	public IApiResult GetById(int id)
	{
		return Ok(id);
	}

	// Explicit [FromRoute(Name = ...)] override: the C# parameter name ("itemId") differs
	// from the placeholder name ("id") in the route template.
	[HttpGet("{id}/details")]
	public IApiResult GetDetails([FromRoute(Name = "id")] int itemId)
	{
		return Ok(itemId);
	}
}

A literal route segment always outranks a placeholder segment for the same request (e.g. a request to v1/items/count matches a literal [HttpGet("count")] action over [HttpGet("{id}")]).

Route parameter values are converted using the same conversion logic as [FromQuery] parameters, so InvalidParameterException is thrown if a route value can't be converted to the parameter's type. Every placeholder must have a matching bound parameter (implicit or [FromRoute]), and every [FromRoute] parameter must reference a placeholder that actually exists in the combined route template — mismatches throw InvalidRouteException eagerly, at Build() time.

[FromQuery] also supports a Name override (e.g. [FromQuery(Name = "q")]), for the same use case with query string parameters.

Repeated query-string keys can bind to arrays and typed collection types such as List<T>, IEnumerable<T>, ICollection<T>, ISet<T>, HashSet<T>, and Collection<T>. Scalar parameters use the first value, while collection parameters receive all values.

Route constraints (e.g. {id:int}) and catch-all/wildcard segments (e.g. {*path}) are not supported.

Access API Context

Access the underlying API request and response through the ApiContext property:

public class MyController : ControllerBase
{
    public IApiResult MyAction()
    {
        var request = this.Request;  // ApiTriggerInput
        var response = this.Response;  // ApiTriggerOutput
        // ...
    }
}

About DataMiner

DataMiner is a transformational platform that provides vendor-independent control and monitoring of devices and services. Out of the box and by design, it addresses key challenges such as security, complexity, multi-cloud, and much more. It has a pronounced open architecture and powerful capabilities enabling users to evolve easily and continuously.

The foundation of DataMiner is its powerful and versatile data acquisition and control layer. With DataMiner, there are no restrictions to what data users can access. Data sources may reside on premises, in the cloud, or in a hybrid setup.

A unique catalog of 7000+ connectors already exists. In addition, you can leverage DataMiner Development Packages to build your own connectors (also known as "protocols" or "drivers").

Note See also: About DataMiner.

About Skyline Communications

At Skyline Communications, we deal in world-class solutions that are deployed by leading companies around the globe. Check out our proven track record and see how we make our customers' lives easier by empowering them to take their operations to the next level.