Add alerts API spec and stub endpoints (#1517)

TeachingRecordSystem/src/TeachingRecordSystem.Api/V3/VNext/ApiModels/PersonInfo.cs

@@ -0,0 +1,10 @@
+namespace TeachingRecordSystem.Api.V3.VNext.ApiModels;
+
+public record PersonInfo
+{
+    public required string Trn { get; init; }
+    public required string FirstName { get; init; }
+    public required string MiddleName { get; init; }
+    public required string LastName { get; init; }
+    public required DateOnly DateOfBirth { get; init; }
+}

TeachingRecordSystem/src/TeachingRecordSystem.Api/V3/VNext/Controllers/AlertsController.cs

@@ -0,0 +1,50 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using Swashbuckle.AspNetCore.Annotations;
+using TeachingRecordSystem.Api.Infrastructure.Security;
+using TeachingRecordSystem.Api.V3.VNext.Requests;
+using TeachingRecordSystem.Api.V3.VNext.Responses;
+
+namespace TeachingRecordSystem.Api.V3.VNext.Controllers;
+
+[Route("alerts")]
+[Authorize(Policy = AuthorizationPolicies.ApiKey, Roles = $"{ApiRoles.UpdateRole}")]
+public class AlertsController : ControllerBase
+{
+    [HttpPost("")]
+    [SwaggerOperation(
+        OperationId = "CreateAlert",
+        Summary = "Create an alert",
+        Description = "Creates an alert for the specified person.")]
+    [ProducesResponseType(typeof(AlertResponse), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    public IActionResult CreateAlert([FromBody] CreateAlertRequestBody request) => throw new NotImplementedException();
+
+    [HttpGet("{alertId}")]
+    [SwaggerOperation(
+        OperationId = "GetAlert",
+        Summary = "Get an alert",
+        Description = "Gets the specified alert.")]
+    [ProducesResponseType(typeof(AlertResponse), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public IActionResult GetAlert([FromRoute] Guid alertId) => throw new NotImplementedException();
+
+    [HttpPatch("{alertId}")]
+    [SwaggerOperation(
+        OperationId = "UpdateAlert",
+        Summary = "Update an alert",
+        Description = "Updates the specified alert.")]
+    [ProducesResponseType(typeof(AlertResponse), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public IActionResult UpdateAlert([FromRoute] Guid alertId, [FromBody] UpdateAlertRequestBody request) => throw new NotImplementedException();
+
+    [HttpDelete("{alertId}")]
+    [SwaggerOperation(
+        OperationId = "DeleteAlert",
+        Summary = "Delete an alert",
+        Description = "Deletes a the specified alert.")]
+    [ProducesResponseType(typeof(void), StatusCodes.Status204NoContent)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public IActionResult DeleteAlert([FromRoute] Guid alertId) => throw new NotImplementedException();
+}

TeachingRecordSystem/src/TeachingRecordSystem.Api/V3/VNext/Requests/CreateAlertRequestBody.cs

@@ -0,0 +1,12 @@
+using Optional;
+
+namespace TeachingRecordSystem.Api.V3.VNext.Requests;
+
+public record CreateAlertRequestBody
+{
+    public required string Trn { get; init; }
+    public required Guid AlertTypeId { get; init; }
+    public required DateOnly StartDate { get; init; }
+    public Option<DateOnly?> EndDate { get; init; }
+    public Option<string?> Details { get; init; }
+}

TeachingRecordSystem/src/TeachingRecordSystem.Api/V3/VNext/Requests/UpdateAlertRequestBody.cs

@@ -0,0 +1,10 @@
+using Optional;
+
+namespace TeachingRecordSystem.Api.V3.VNext.Requests;
+
+public record UpdateAlertRequestBody
+{
+    public Option<DateOnly> StartDate { get; init; }
+    public Option<DateOnly?> EndDate { get; init; }
+    public Option<string?> Details { get; init; }
+}

TeachingRecordSystem/src/TeachingRecordSystem.Api/V3/VNext/Responses/AlertResponse.cs

@@ -0,0 +1,8 @@
+using TeachingRecordSystem.Api.V3.VNext.ApiModels;
+
+namespace TeachingRecordSystem.Api.V3.VNext.Responses;
+
+public record AlertResponse : Alert
+{
+    public required PersonInfo Person { get; init; }
+}

TeachingRecordSystem/src/TeachingRecordSystem.Core/ApiRoles.cs

@@ -9,6 +9,7 @@ public static class ApiRoles
     public const string CreateTrn = "CreateTrn";
     public const string AssignQtls = "AssignQtls";
     public const string AppropriateBody = "AppropriateBody";
+    public const string UpdateRole = "UpdateRole";
 
     public static IReadOnlyCollection<string> All { get; } = new[]
     {
@@ -19,5 +20,6 @@ public static class ApiRoles
         CreateTrn,
         AssignQtls,
         AppropriateBody,
+        UpdateRole,
     };
 }

docs/api-designs/alerts.md

@@ -0,0 +1,96 @@
+# Alerts API
+
+Draft specification v0.1.
+
+
+## `POST /alerts`
+
+Creates an alert.
+
+Request body structure:
+```json
+{
+  "trn": "",
+  "alertTypeId": "",
+  "startDate": "",
+  "endDate": "",
+  "details": ""
+}
+```
+
+If no record exists with the specified TRN, a `400 Bad Request` status code will be returned.
+
+The `startDate` and `endDate` properties must be formatted `yyyy-MM-dd`.
+`startDate` cannot be `null`.
+The `endDate` and `details` properties are optional.
+If specified, the `endDate` property must be after the `startDate`.
+
+If the alert was created successfully, a `201 Created` status code will be returned.
+
+The response returned is identical to that of the [`GET` endpoint](#get-alertsalertid).
+
+
+## `GET /alerts/<alertId>`
+
+Retrieves an alert.
+
+If no alert exists with the specified ID, a `404 Not Found` status code will be returned.
+
+If the alert exists, a `200 OK` status code will be returned with the following response body:
+
+```json
+{
+  "alertId": "",
+  "alertType": {
+    "alertTypeId": "",
+    "name": "",
+    "alertCategory": {
+      "alertCategoryId": "",
+      "name": ""
+    }
+  },
+  "startDate": "",
+  "endDate": "",
+  "person": {
+    "trn": "",
+    "firstName": "",
+    "middleName": "",
+    "lastName": "",
+    "dateOfBirth": ""
+  }
+}
+```
+
+
+## `PATCH /alerts/<alertId>`
+
+Updates an alert.
+
+Request body structure:
+```json
+{
+  "alertId": "",
+  "startDate": "",
+  "endDate": "",
+  "details": ""
+}
+```
+
+If no alert exists with the specified ID, a `404 Not Found` status code will be returned.
+
+The `startDate` and `endDate` properties must be formatted `yyyy-MM-dd`.
+All properties are optional; only the properties specified will be updated.
+If specified, the `endDate` property must be after the `startDate`.
+
+If the alert was updated successfully, an `200 OK` status code will be returned.
+
+The response returned is identical to that of the [`GET` endpoint](#get-alertsalertid).
+
+
+## `DELETE /alerts/<alertId>`
+
+Deletes an alert.
+
+If no alert exists with the specified ID, a `404 Not Found` status code will be returned.
+
+If the alert was deleted successfully, a `204 No Content` status code will be returned.