Skip to content

Commit

Permalink
Add alerts API spec and stub endpoints (#1517)
Browse files Browse the repository at this point in the history
  • Loading branch information
gunndabad authored Sep 17, 2024
1 parent 205248d commit 5365649
Show file tree
Hide file tree
Showing 7 changed files with 188 additions and 0 deletions.
Original file line number Diff line number Diff line change
@@ -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; }
}
Original file line number Diff line number Diff line change
@@ -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();
}
Original file line number Diff line number Diff line change
@@ -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; }
}
Original file line number Diff line number Diff line change
@@ -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; }
}
Original file line number Diff line number Diff line change
@@ -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; }
}
Original file line number Diff line number Diff line change
Expand Up @@ -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[]
{
Expand All @@ -19,5 +20,6 @@ public static class ApiRoles
CreateTrn,
AssignQtls,
AppropriateBody,
UpdateRole,
};
}
96 changes: 96 additions & 0 deletions docs/api-designs/alerts.md
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit 5365649

Please sign in to comment.