Endpoints

Overview

The Endpoints-feature provides a easy way to automatically define endpoints for available DataSources from the System.

Here is a brief overview of what happens when a defined endpoint is called

Endpoint-Builder

For convenience, a EndpointBuilder is available that generates EndpointDefinitionModels. Here is a overview of the builder:

General Configuration

Create

Initializes the EndpointBuilder for the given base-configuration.

Usage

EndpointBuilder.Create(string name, string routeTemplate, HttpMethod method, EndpointSecurityConfigurationBuilder securityConfigurationBuilder = null)

Parameters

• name: The name of the endpoint.
• routeTemplate: The route template for the endpoint.
• method: The HTTP method for the endpoint.
• securityConfigurationBuilder: (Optional) Security configuration builder.

AsSystemDefined

Defines a Endpoint as SystemDefined. This tells the system that the Endpoint is always created on startup of the system. SystemDefined Endpoints are automatically removed if the code does not explicitly define them again.

Usage

EndpointBuilder.AsSystemDefined()

Description

Marks the endpoint as system-defined.

Build

Executes the builder and generates the configured EndpointDefinitionModel.

Usage

EndpointBuilder.Build()

Description

Builds and returns an EndpointDefinitionModel object based on the configuration.

DataSource Configuration

WithDataSource

Defines the DataSource that this Endpoint should use. The DataSourceKey can be generated using a IDataSourceKeyManager to always use correct datasource-keys.

Usage

EndpointBuilder.WithDataSource(string dataSourceKey)

Parameters

• dataSourceKey: Key identifying the data source.

Mapping Configuration (Input/Output)

A mapping configuration must be defined for both the input-data and for the output-data. Each mappers can and mostly will be different, as the InputMapping maps the parameters from the endpoint to the data the DataSource expects and the OutputMapping maps the result of the DataSource to what is expected to be returned in the Endpoint.

note

The OutputMapping datatype will be used to generate the Swagger-Documentation for this endpoint

WithInputMapping / WithOutputMapping

Defines the mapper-type to use for either the input or the output mapping and optionally defines all the property-mappings.

note

This is the generic implementation for a mapping-configuration, better use one of the specific implementations below.

Usage

EndpointBuilder.With[Input/Output]Mapping<TSource, TDestination>(string mapperTypeDiscriminator, Action<PropertyMappingBuilder<TSource>> propertyBuilder = null)

Parameters

• mapperTypeDiscriminator: The type discriminator for the mapper.
• propertyBuilder: (Optional) Action to configure the property mappings.

WithInputOneToOneMapping / WithOutputOneToOneMapping

Defines a One-to-One mapping of the given TData type. Input- and Ouput-type are identical and will be mapped directly.

Usage

EndpointBuilder.With[Input/Output]OneToOneMapping<TData>()

Description

Sets up a one-to-one mapping configuration.

WithInputFilteringMapping / WithOutputFilteringMapping

Defines a filtering mapper. This works the same way as the One-to-One mapper, but the mapped properties must be defined in the propertyBuilder parameter. All undefined properties are ignored and not mapped.

Usage

EndpointBuilder.With[Input/Output]FilteringMapping<TData>(Action<PropertyMappingBuilder<TData>> propertyBuilder)

Parameters

• propertyBuilder: Action to configure the property mappings.

WithNoInputMapping / WithNoOutputMapping

Defines a mapper where nothing is mapped. This must be used when there is no output or when the output of the DataSource should be omitted.

Usage

EndpointBuilder.WithNo[Input/Output]Mapping()

Description

Specifies that there should be no mapping for the endpoint.

Parameters Configuration

The following methods are used to define the input-parameters of this endpoint. Each input-parameter will be mapped to the Swagger-Documentation. Set a defaultValue to make this parameter optional.

WithParameter

Defines a dynamic parameter that is read from the given parameter location (either Path, Query or Body).

Usage

EndpointBuilder.WithParameter<TParameter>(string name, EndpointParameterLocation location, TParameter defaultValue = default)

Parameters

• name: The name of the parameter.
• location: The location of the parameter (Path, Query, etc.).
• defaultValue: (Optional) The default value of the parameter.

WithStaticParameter

Defines a static paramter that is eg required by the DataSource but should not be available in the Endpoint as parameter.

Usage

EndpointBuilder.WithStaticParameter<TParameter>(string name, TParameter value)

Parameters

• name: The name of the parameter.
• value: The value of the parameter.

Security Configuration

Defines the security-configurations for the endpoint. By default, each Endpoint is not public available and requires always a bearer token. To define a anonymous-callable endpoint, define the configuration as c => c.AllowAnonymous().

WithSecurityConfiguration

Usage

EndpointBuilder.WithSecurityConfiguration(Action<EndpointSecurityConfigurationBuilder> configuration)

Parameters

• configuration: Action to configure the security settings.

Configuration reference

EndpointDefinitionModel

Property Name	Description
Name	The name of the endpoint.
RouteTemplate	The route template for the endpoint.
HttpMethod	The HTTP method used by the endpoint.
DataSourceKey	Key identifying the data source.
InputMapperTypeDiscriminator	Discriminator for selecting the input mapper.
InputMappingConfiguration	Configuration for input mapping. See MappingConfigurationModel.
OutputMapperTypeDiscriminator	Discriminator for selecting the output mapper.
OutputMappingConfiguration	Configuration for output mapping. See MappingConfigurationModel.
Parameters	Definitions for endpoint parameters. See EndpointParameterDefinitionModel.
IsSystemDefined	Indicates if the endpoint is system-defined.
SecurityConfiguration	Security configuration for the endpoint. See EndpointSecurityConfigurationModel.

MappingConfigurationModel

Property Name	Description
SourceType	The type of the source object for mapping.
DestinationType	The type of the destination object for mapping.
PropertyMappings	Collection of mappings between properties. See PropertyMappingModel.

PropertyMappingModel

Property Name	Description
SourcePropertySelector	Selector for the source property to map.
DestinationProperty	The destination property for the mapping.
ChildPropertyMappings	Mappings for nested properties. See PropertyMappingModel.

EndpointParameterDefinitionModel

Property Name	Description
Name	The name of the parameter.
Type	The data type of the parameter.
Location	The location of the parameter (Path, Query, etc.).
DefaultValue	The default value of the parameter.

EndpointSecurityConfigurationModel

Property Name	Description
AllowAnonymous	Indicates whether anonymous access is allowed.
SecurityPolicies	Array of security policies applied to the endpoint.
Roles	Array of roles required to access the endpoint.