new-endpoint

name	new-endpoint
description	Scaffold a new vertical-slice endpoint in oed-admin.Server following the Features/<Area>/<Operation>/ convention, and register it in Features/Endpoints.cs with an authorization policy. Use when adding an API route to the admin backend.

Adding an endpoint to oed-admin.Server

Endpoints here are vertical slices. There is no service or repository layer: the handler injects OedDbContext / AuthzDbContext / a typed Altinn client with [FromServices] and does the work.

Ask for the area, operation, and HTTP verb if the user has not given them. Area is an existing folder under Features/ (Estate, Tasks, Instances, Superadmin, EventSubscriptions, Maintenance, DistrictCourts) or a new one.

Steps

1. Create oed-admin.Server/Features/<Area>/<Operation>/ with Endpoint.cs, Request.cs, and Response.cs. See references/endpoint-template.cs for the exact shape. Rules that matter:

• Endpoint is a static class with a single static method named after the verb (Get, Post, Patch, Delete) returning Task<IResult>.
• Bind route/query params with [AsParameters] Request request; bind a JSON body with [FromBody] Request request.
• First line of the handler is the validation guard: if (!request.IsValid()) return TypedResults.BadRequest();
• Request is a record with a hand-rolled IsValid(). Compare GUIDs against Guid.Empty, never default.
• Read queries use .AsNoTracking(). This app is read-mostly against databases owned by other services — never add an EF Core migration here.
• Map entity → DTO with PoorMansMapper.Map<TFrom, TTo>(entity). It copies name-matching properties by reflection, so only give the DTO the properties you intend to expose.
• A "not found" result is usually TypedResults.Ok(new Response(null)), not a 404 — match the neighbouring slices in the same area.

2. Register the route in oed-admin.Server/Features/Endpoints.cs. The endpoint does not exist until you do this — nothing fails at build time, the route is simply absent.

Add it to the matching Map<Area>Endpoints() extension method inside the extension(WebApplication app) block, or as a top-level app.MapX(...) if the area has no group.

3. Attach an authorization policy. Group registrations already carry .RequireAuthorization(AuthorizationPolicies.RequireAdminRole), so a route added to an existing group inherits it. A new top-level route needs its own:

• AuthorizationPolicies.RequireAdminRole — the default. Use unless told otherwise.
• AuthorizationPolicies.AtLeastReadRole — only for read-only lookups that expose no identifying personal data (no DeceasedNin, DeceasedName, DeceasedPartyId, date of death).

Never add an unauthenticated route. GET /api/qa is the sole intentional exception and it stays that way.

4. Check the audit trail. AuditingLoggingMiddleware extracts affected estate ids from the {estateId} route value, or — for POST — by deserializing the response as PartialSearchResponse (an Estate object, or an Estates array of items with Id).

If the new endpoint returns estate data but has neither, the audit record will have no estate ids. Either add {estateId:guid} to the route, shape the response to match, or raise it with the user. Do not quietly ship an unaudited personal-data lookup.

5. Client side, if asked. Add a query-key factory and hook under oed-admin.client/src/queries/, following taskQueries.ts. Fetch through fetchWithMsal from utils/msalUtils.ts — never bare fetch, which would send the request without a bearer token.

Verify

dotnet build oed-admin.Server/oed-admin.Server.csproj

Then confirm the route appears: run the server and check the Scalar UI at /scalar (Development and Staging only), or grep Features/Endpoints.cs for the new symbol.