Skip to content
ProvEn 2.0

API

Proven 2.0 is designed to be interacted with via a REST API, providing more feedback and control over requests over the original queue-based model.

The API is built on ASP.NET Core with OData.

Endpoints

Section titled “Endpoints”

All endpoints are defined under the v1 route to allow easier versioning in future. These are split across two endpoints:

  • TenantsController - The main controller for interacting with the engine.
  • OSToLatLongController - Legacy endpoints used by an integration for converting OS references to lat/long coordinates.

All TenantsController endpoints require authentication and sufficient authorisation. OSToLatLongController endpoints are open.

Endpoints under the tenants controller are hierarchically organised, and offer both a traditional REST format (/tenants/tenantId/jobs) as well as a standard OData format (/tenants(tenantId)/jobs).

Authentication & Authorization

Section titled “Authentication & Authorization”

Rather than using the Azure Web App authentication layer, authentication is handled in-app. This allows for easier integration of authorisation.

The API enforces two policies:

  • Privileged - Requires that a ‘privileged’ user performs the request. Currently, this means any app/user based inside the Core tenant.
  • PrivilegedOrTenant - Requires a privileged user (as above) OR that the user/app is located in the tenant that matches the queried resource. For example, /tenants/<tenantId>/jobs would require that you are authenticated from <tenantId>.

These policies are defined in the startup file Program.cs.

Additionally, the presence of specific API scopes on certain routes is enforced. This allows endpoints to be called only if the token contains the required scopes, allowing an app registration to control its scope to maximise security.

Policies and endpoints are added to a route using attributes. An example route definition is shown below.

[EnableQuery]
[Authorize(Policy = Policies.PrivilegedOrTenant)]
[RequiredScopeOrAppPermission(RequiredAppPermissionsConfigurationKey = "AzureAd:AppPermissions:Job.Read")]
public async Task<IActionResult> GetJobs(Guid key)
{
    // implementation
}