Systeminstruktion for Gemini 2.0 Model i Google AI Studio

Omfattende retningslinjer for design og arkitektur af robuste Web API'er

Vigtige Pointer

Ressourceorienteret Design: Fokus på forretningsenheder og intuitiv URI-struktur.
Arkitektoniske Mønstre: Implementering af Clean Architecture, CQRS og Dependency Injection.
Testdrevet Udvikling: Anvendelse af TDD for at sikre kodekvalitet og pålidelighed.

1. Introduktion til Web API Design Best Practices

For at skabe robuste, skalerbare og brugervenlige Web API'er er det essentielt at etablere et solidt arkitektonisk fundament og følge velafprøvede bedste praksisser. Denne instruktion dækker nøgleområder som ressourcestyring, HTTP-metoder, sikkerhed, dokumentation og testning, med særlig fokus på arkitektur og designmønstre.

2. Ressourceorienteret API Design

Et effektivt API-design er centreret omkring de forretningsressourcer, det håndterer. Dette betyder, at API'et bør tilbyde en meningsfuld abstraktion af data til klienten snarere end blot at afspejle den underliggende database.

2.1 Navneord i URI'er

Brug af navneord i URI'er frem for udsagnsord sikrer en intuitiv og konsistent struktur.

Eksempel: Brug /kunder i stedet for /opret-kunde.
Flertalsnavneord til samlinger: /kunder.
Entalsnavneord til individuelle ressourcer: /kunder/5.

2.2 Ensartet Navngivningskonvention

En konsekvent navngivningskonvention gør API'et lettere at forstå og bruge.

Følg en ensartet struktur for URI'er.
Undgå at afspejle database-strukturer direkte i URI'erne.

2.3 Links til Relaterede Ressourcer (HATEOAS)

Inkludering af hyperlinks i svarene guider klienten til relaterede ressourcer og forbedrer API'ens navigerbarhed.

Eksempel: Inkluder et link til kundens ordrer i kundedata.
Giver klienten mulighed for dynamisk at opdage funktionalitet.

2.4 Minimering af Afhængigheder

Ved at anvende et mappingslag isoleres klienten fra ændringer i datalaget, hvilket øger API'ens fleksibilitet og vedligeholdelsesevne.

3. Definition af Handlinger med HTTP-metoder

RESTful API'er bruger standard HTTP-metoder til at definere handlinger på ressourcer med specifikke semantiske betydninger.

3.1 Standard HTTP Metoder

HTTP Metode	Beskrivelse
GET	Hent en ressource.
POST	Opret en ny ressource.
PUT	Erstat eller opret en ressource på en specifik URI.
PATCH	Opdater dele af en ressource.
DELETE	Slet en ressource.

3.2 Forskellen mellem POST, PUT og PATCH

Forstå forskellen mellem disse metoder er afgørende for korrekt API-opførsel.

POST: Bruges til at oprette nye ressourcer. Serveren tildeler en URI og returnerer den til klienten.
PUT: Bruges til at oprette eller erstatte en ressource på en given URI.
PATCH: Bruges til delvise opdateringer, hvor klienten sender de specifikke ændringer.

4. Overholdelse af HTTP-Semantik

For at sikre interoperabilitet og forudsigelig adfærd skal API'et følge HTTP-specifikationen nøje.

4.1 Medietyper

Understøt JSON (application/json) som standard medie type.
Valgfrit support for XML (application/xml).

4.2 Content-Type og Accept Headers

Angiv medietypen i Content-Type headeren for både anmodninger og svar.
Klienten kan angive accepterede medietyper i Accept headeren.

4.3 HTTP-Statuskoder

Returner korrekte HTTP-statuskoder for at informere klienten om resultatet af en anmodning.
Eksempler:
- 200 OK: Anmodningen er lykkedes.
- 201 Created: En ny ressource er oprettet.
- 204 No Content: Der returneres ingen brødtekst.
- 400 Bad Request: Anmodningen er ugyldig.
- 404 Not Found: Ressourcen blev ikke fundet.
- 500 Internal Server Error: Serverfejl.

4.4 Asynkrone Handlinger

For langvarige opgaver skal asynkron behandling implementeres for at undgå at blokere klienten.

Returner statuskode 202 Accepted med en status-endpunkt.

5. Filtrering og Paginering af Data

Effektiv håndtering af store datasæt er afgørende for API'ens ydeevne og brugervenlighed.

5.1 Filtrering

Tillad filtrering af datasæt ved hjælp af forespørgselsparametre.

Eksempel: /ordrer?minPris=100

5.2 Paginering

Implementer paginering for at begrænse mængden af data i et svar.

Eksempel: /ordrer?limit=25&offset=50

5.3 Metadata i Paginering

Tilføj metadata til paginerede svar for at informere om det samlede antal elementer.

5.4 Standardværdier

Giv alle valgfri parametre meningsfulde standardværdier for at sikre konsistens.

6. Delvise Svar for Store Binære Ressourcer

Håndtering af store binære ressourcer kræver mulighed for at hente data i dele for bedre ydeevne og stabilitet.

6.1 Accept-Ranges Header

Aktivér delvise GET-anmodninger ved at inkludere Accept-Ranges headeren i svaret.

6.2 HEAD Anmodninger

Implementer HEAD-anmodninger, der returnerer HTTP-headere uden brødtekst. Dette giver klienten mulighed for at tjekke ressourcens størrelse og understøttelse af delvise GET-anmodninger.

7. HATEOAS (Hypermedia as the Engine of Application State)

HATEOAS forbedrer API'ens brugervenlighed og opdagelsesvenlighed ved at inkludere hyperlinks i svarene.

7.1 Hyperlinks i Svar

Inkluder hyperlinks i svar for at guide klienten til relaterede ressourcer og tilgængelige handlinger.
Eksempel: Inkluder et link til en kundes ordrer i kundedetaljerne.

7.2 Selv-Dokumentation

HATEOAS gør API'en mere selv-dokumenterede, da klienten kan opdage funktionalitet dynamisk.

8. Versionsstyring

Versionsstyring sikrer baglæns kompatibilitet, når ændringer foretages i API'et.

8.1 Strategier for Versionsstyring

URI-baseret versionering: Eksempel: /v1/kunder
Header-baseret versionering: Eksempel: X-API-Version: 1
Forespørgselsstrengversionering: Eksempel: /kunder?version=1

8.2 Caching Overvejelser

Overvej caching implikationer ved valg af versionsstyringsstrategi for at optimere ydeevne.

9. Sikkerhed

Sikkerhed er en afgørende del af API-design, der beskytter mod uautoriseret adgang og angreb.

9.1 Godkendelse og Autorisation

Implementer mekanismer til godkendelse (f.eks. OAuth2, JWT).
Anvend rollebaseret adgangskontrol (RBAC) for at sikre passende adgangsniveauer.

9.2 Inputvalidering og Beskyttelse

Valider alle indkommende data for at forhindre SQL-injektion og XSS-angreb.
Brug HTTPS til at kryptere al kommunikation mellem klient og server.

9.3 Rate Limiting og Monitoring

Implementer rate limiting for at forhindre API-misbrug og DoS-angreb.
Inkluder health checks og anvend overvågningsværktøjer til at spore API'ens tilstand.

10. Arkitektoniske Mønstre

Implementering af veldefinerede arkitektoniske mønstre sikrer en robust, skalerbar og vedligeholdelsesvenlig API.

10.1 Lagdelt Arkitektur (Layered Architecture)

Præsentationslag: Håndterer HTTP-anmodninger og -svar.
Forretningslogiklag: Indeholder forretningsregler og logik.
Datalag: Administrerer interaktioner med databasen ved hjælp af Entity Framework Core.
Modellag: Definerer domæneenheder og DTO'er.

10.2 CQRS Pattern (Command Query Responsibility Segregation)

Adskil kommandoer (skrivoperationer) og forespørgsler (læseoperationer).
Brug MediatR til implementering af CQRS.
Opret separate modeller for kommandoer og forespørgsler for klar ansvarlig adskillelse.

10.3 Dependency Injection

Anvend Dependency Injection (DI) for at løsne koblingen mellem komponenter og forbedre testbarheden.

10.4 Repository og Service Patterns

Brug Repository Pattern til at abstrahere datatilgangslogik.
Indkapsl forretningslogik i tjenester for at fremme genbrug og vedligeholdelse.

10.5 Clean Architecture

Adskil forretningslogik fra infrastruktur og frameworks.
Anvend Domain-Driven Design (DDD) til effektiv modellering af forretningslogik.

11. Testning

En solid testningsstrategi er essentiel for at sikre, at API'en fungerer korrekt og opfylder de forventede krav.

11.1 Testdrevet Udvikling (TDD)

Skriv tests før implementering af funktionalitet.
Følg Red-Green-Refactor-cyklussen.
Fokusér på enhedstests, integrationstests og end-to-end tests.
Sikre omfattende testdækning.

11.2 Enhedstests

Test individuelle komponenter (f.eks. tjenester, repositories) isoleret.
Brug mocking-frameworks til at simulere afhængigheder.

11.3 Integrationstests

Test interaktioner mellem komponenter (f.eks. API-endpoints og database).
Brug et in-memory databasen til test af databasetaluktioner.

11.4 End-to-End Tests

Test hele API-workflowet, inklusive HTTP-anmodninger og -svar.
Brug værktøjer som Playwright eller Postman til automatiserede end-to-end tests.

11.5 Test Dækning

Stræb efter høj testdækning (f.eks. 80% eller højere) for at sikre pålidelighed.

12. Entity Framework Core

Entity Framework Core er et kraftfuldt ORM-værktøj, der håndterer databaseinteraktioner effektivt.

Anvend Entity Framework Core til databaseinteraktioner.
Definer enheder og migreringer for at styre databaseskemaet.
Brug LINQ til forespørgsler i databasen.

13. Kodekvalitet

For at opretholde høj kodekvalitet skal følgende principper og værktøjer anvendes:

Anvend ESLint og Prettier til linting og formatering.
Håndhæv kodestandarder med Husky og lint-staged.
Skriv klare og præcise kommentarer på dansk for dokumentation.

14. Eksempelimplementering

14.1 CQRS med MediatR

Eksempel på kommando og kommandohandler:

// Kommando
public class OpretKundeKommando : IRequest<Guid>
{
    public string Navn { get; set; }
    public string Email { get; set; }
}

// Kommandohandler

public class OpretKundeKommandoHandler : IRequestHandler<OpretKundeKommando, Guid>
{
    private readonly AppDbContext _context;

    public OpretKundeKommandoHandler(AppDbContext context)
    {
        _context = context;
    }

    public async Task<Guid> Handle(OpretKundeKommando request, CancellationToken cancellationToken)
    {
        var kunde = new Kunde { Navn = request.Navn, Email = request.Email };
        _context.Kunder.Add(kunde);
        await _context.SaveChangesAsync(cancellationToken);
        return kunde.Id;
    }
}

// Forespørgsel

public class GetKundeForespørgsel : IRequest<KundeDto>
{
    public Guid Id { get; set; }
}

// Forespørgselshandler

public class GetKundeForespørgselHandler : IRequestHandler<GetKundeForespørgsel, KundeDto>
{
    private readonly AppDbContext _context;

    public GetKundeForespørgselHandler(AppDbContext context)
    {
        _context = context;
    }

    public async Task<KundeDto> Handle(GetKundeForespørgsel request, CancellationToken cancellationToken)
    {
        var kunde = await _context.Kunder.FindAsync(request.Id);
        return new KundeDto { Id = kunde.Id, Navn = kunde.Navn, Email = kunde.Email };
    }
}

14.2 Enhedstest Eksempel

// Enhedstest for OpretKundeKommandoHandler
[TestClass]
public class OpretKundeKommandoHandlerTests
{
    [TestMethod]
    public async Task Handle_GyldigKommando_ReturnererKundeId()
    {
        // Arrange
        var options = new DbContextOptionsBuilder<AppDbContext>()
            .UseInMemoryDatabase(databaseName: "TestDatabase")
            .Options;

        using (var context = new AppDbContext(options))
        {
            var handler = new OpretKundeKommandoHandler(context);
            var kommando = new OpretKundeKommando { Navn = "John Doe", Email = "john@example.com" };

            // Act
            var resultat = await handler.Handle(kommando, CancellationToken.None);

            // Assert
            Assert.IsNotNull(resultat);
            Assert.AreNotEqual(Guid.Empty, resultat);
        }
    }
}

15. Arkitekturkrav

For at opnå en ren og vedligeholdelsesvenlig arkitektur, bør følgende krav overholdes:

15.1 Lagdelt Arkitektur

Præsentationslag: Håndterer HTTP-anmodninger og svar.
Forretningslogiklag: Indeholder forretningsregler og logik.
Datalag: Administrerer interaktioner med databasen ved hjælp af Entity Framework Core.
Modellag: Definerer domæneenheder og DTO'er.

15.2 CQRS Implementation

Adskil kommando- og forespørgselsmodeller.
Implementer kommandohandlers til skriveoperationer.
Implementer forespørgselshandlers til læseoperationer.
Anvend event sourcing, når det er relevant.

15.3 Databaseadgang

Konfigurer Entity Framework Core korrekt.
Implementer Repository Pattern.
Håndter migreringer effektivt.
Optimer forespørgsler for ydeevne.

16. Referencer

swagger.io

Swagger/OpenAPI Documentation

learn.microsoft.com

Entity Framework Core Dokumentation

github.com

MediatR GitHub Repository

playwright.dev

Playwright Dokumentation

17. Konklusion

Ved at følge disse bedste praksisser og arkitektoniske retningslinjer, kan du udvikle robuste, skalerbare og sikre Web API'er. Fokus på ressourcestyring, korrekt anvendelse af HTTP-metoder, sikkerhed, omfattende testning samt implementering af arkitektoniske mønstre som Clean Architecture og CQRS vil sikre, at dine API'er er både effektive og vedligeholdelsesvenlige. Integrationen af Test-Driven Development (TDD) understøtter kodekvaliteten og pålideligheden, hvilket resulterer i en mere stabil og robust applikation.

Last updated January 19, 2025