Hier is een voorbeeld van een REST API-documentatie voor "MijnService API" met Swagger (OpenAPI 3.0) specificatie. Deze documentatie beschrijft de verschillende gebruikersrollen, toegangsrechten en geeft richtlijnen voor beveiliging en autorisatie. --- # MijnService API - Documentatie ## Inleiding Deze API biedt verschillende endpoints voor het beheren van resources binnen MijnService. Toegang tot deze endpoints is gebaseerd op gebruikersrollen met verschillende toegangsrechten. De rollen zijn: - **Admin**: Volledige toegang, inclusief beheer van gebruikers en alle resources. - **Editor**: Kan content bewerken en toevoegen. - **Viewer**: Alleen lezen, geen bewerkingen toegestaan. ## Rollen en Toegangsrechten | Rol | Toegangsrechten | Voorbeelden van toegankelijke endpoints | |---------|--------------------------------------------------------------|--------------------------------------------------------------------------------------| | Admin | Volledige controle, inclusief gebruikersbeheer en alle resources | `/users`, `/settings`, `/resources` | | Editor | Content bewerken, toevoegen, maar geen gebruikersbeheer | `/resources`, `/resources/{id}` | | Viewer | Alleen lezen, geen bewerkingen | `/resources`, `/resources/{id}` | --- ## Beveiliging en Authenticatie Deze API maakt gebruik van **Bearer Token** authenticatie. Elke aanvraag moet een geldig JWT-token bevatten in de `Authorization` header: ``` Authorization: Bearer {your_jwt_token} ``` Het token bevat claims die de gebruikersrol aangeven, bijvoorbeeld: ```json { "sub": "user123", "role": "Admin", "iat": 1616161616 } ``` ### Richtlijnen voor het beheren van beveiligingsniveaus - Gebruik HTTPS voor alle communicatie. - Implementeer JWT-validatie en controleer de rol claim. - Beperk toegangsrechten op serverniveau door middel van middleware die de rol controleert voordat een endpoint wordt bereikt. - Voor endpoints met beperkte toegang, documenteer duidelijk dat een rol vereist is, en geef voorbeelden van vereiste claims. --- ## Swagger/OpenAPI Specificatie (voorbeeld) ```yaml openapi: 3.0.3 info: title: MijnService API description: > API voor MijnService met geavanceerde gebruikersrollen en toegangsbeheer. version: 1.0.0 components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT security: - BearerAuth: [] paths: /resources: get: summary: Bekijk alle resources security: - BearerAuth: [] responses: '200': description: Lijst van resources description: | Alleen toegestaan voor: Admin, Editor, Viewer. post: summary: Voeg een nieuwe resource toe security: - BearerAuth: [] responses: '201': description: Resource aangemaakt description: | Alleen toegestaan voor: Admin, Editor. /resources/{id}: get: summary: Bekijk een resource security: - BearerAuth: [] responses: '200': description: Details van de resource description: | Alleen toegestaan voor: Admin, Editor, Viewer. put: summary: Werk een resource bij security: - BearerAuth: [] responses: '200': description: Resource bijgewerkt description: | Alleen toegestaan voor: Admin, Editor. delete: summary: Verwijder een resource security: - BearerAuth: [] responses: '204': description: Resource verwijderd description: | Alleen toegestaan voor: Admin. # Rollen en toegangscontrole op serverniveau # (Voorbeeld van pseudocode) # middleware.checkRole(['Admin', 'Editor']) # middleware.checkRole(['Admin']) # middleware.checkRole(['Admin', 'Editor', 'Viewer']) ``` --- ## Aanbevelingen voor ontwikkelaars - Implementeer JWT-verificatie en controleer de rol claim voor elke endpoint. - Beperk write- en delete-toegang tot Admin en Editor. - Laat Viewer-rollen alleen GET-verzoeken uitvoeren. - Documenteer duidelijk welke endpoints per rol toegankelijk zijn. - Gebruik statuscodes en foutmeldingen om de gebruiker te informeren over toegangsbeperkingen. --- Heeft u nog verdere wensen voor de documentatie of specifieke endpoints?

Zeker, hier is een gedetailleerde REST API-documentatie voor MijnService API met Swagger/OpenAPI 3.0-formaat, gericht op geavanceerde gebruikersrollen en toegangsbeheer. --- # MijnService API Documentatie ## 📋 Inleiding De MijnService API biedt een veilige en schaalbare interface voor het beheren van applicatiedata. Deze documentatie beschrijft de autorisatiestructuur op basis van gebruikersrollen. ## 🔐 Autorisatie ### Gebruikersrollen | Rol | Beschrijving | Toegangsniveau | |-----|--------------|----------------| | Admin | Volledig systeembeheer | CRUD op alle resources | | Editor | Contentbeheerder | CRUD op content, beperkte systeemtoegang | | Viewer | Alleen-lezen gebruiker | Alleen GET-operaties | ### Authenticatie ```yaml Bearer Auth: JWT-token vereist in Authorization header Format: Authorization: Bearer <JWT_TOKEN> ``` ## 📊 Endpoint Overzicht per Rol ### Gebruikersbeheer Endpoints ```yaml /api/v1/users: get: summary: Gebruikerslijst ophalen security: - bearerAuth: [] responses: '200': description: Succes content: application/json: schema: type: array items: $ref: '#/components/schemas/User' x-roles-toegang: ['Admin'] # Alleen Admin post: summary: Nieuwe gebruiker aanmaken security: - bearerAuth: [] x-roles-toegang: ['Admin'] # Alleen Admin /api/v1/users/{id}: put: summary: Gebruiker bijwerken x-roles-toegang: ['Admin'] # Alleen Admin delete: summary: Gebruiker verwijderen x-roles-toegang: ['Admin'] # Alleen Admin ``` ### Content Management Endpoints ```yaml /api/v1/articles: get: summary: Artikelen ophalen x-roles-toegang: ['Admin', 'Editor', 'Viewer'] # Alle rollen post: summary: Artikel aanmaken x-roles-toegang: ['Admin', 'Editor'] # Admin + Editor /api/v1/articles/{id}: get: summary: Specifiek artikel ophalen x-roles-toegang: ['Admin', 'Editor', 'Viewer'] # Alle rollen put: summary: Artikel bijwerken x-roles-toegang: ['Admin', 'Editor'] # Admin + Editor delete: summary: Artikel verwijderen x-roles-toegang: ['Admin'] # Alleen Admin ``` ### Systeembeheer Endpoints ```yaml /api/v1/system/logs: get: summary: Systeemlogs ophalen x-roles-toegang: ['Admin'] # Alleen Admin /api/v1/system/health: get: summary: Systeemstatus controleren x-roles-toegang: ['Admin', 'Editor'] # Admin + Editor ``` ## 🛡️ Beveiligingsrichtlijnen ### 1. JWT Token Implementatie ```yaml JWT Payload Voorbeeld: { "sub": "gebruiker123", "roles": ["Editor"], "permissions": ["articles:read", "articles:write"], "exp": 1672531200 } ``` ### 2. Toegangscontrole Lagen ```yaml Aanbevolen implementatie: 1. API Gateway Level: Basis JWT validatie 2. Middleware Level: Rol-validatie per endpoint 3. Service Level: Fijnmazige permissie-controle 4. Database Level: Row-level security waar nodig ``` ### 3. Foutafhandeling ```http HTTP/1.1 403 Forbidden Content-Type: application/json { "error": "Forbidden", "message": "Onvoldoende rechten voor deze actie", "requiredRole": "Admin", "currentRole": "Viewer" } ``` ## 🔧 Implementatie Voorbeelden ### Middleware Voorbeeld (Node.js) ```javascript const roleMiddleware = (requiredRoles) => { return (req, res, next) => { const userRoles = req.user.roles; const hasAccess = requiredRoles.some(role => userRoles.includes(role)); if (!hasAccess) { return res.status(403).json({ error: 'Toegang geweigerd', requiredRoles, userRoles }); } next(); }; }; // Gebruik app.get('/admin/users', roleMiddleware(['Admin']), usersController.getUsers); ``` ### Test Cases ```yaml Test Scenario's: - Viewer probeert gebruiker aan te maken: 403 Forbidden - Editor wijzigt artikel: 200 OK - Admin verwijdert gebruiker: 200 OK - Onbevoegde toegang systeemlogs: 403 Forbidden ``` ## 📈 Best Practices ### 1. Principle of Least Privilege - Ken minimale benodigde rechten toe - Review rollen regelmatig - Implementeer tijdelijke toegang indien nodig ### 2. Beveiligingsaudit ```yaml Audit Logging: - Alle toegangspogingen loggen - Wijzigingen in gebruikersrollen tracken - Regelmatige security reviews ``` ### 3. Rate Limiting ```yaml Rate Limits per Rol: - Admin: 1000 requests/minuut - Editor: 500 requests/minuut - Viewer: 100 requests/minuut ``` ## 🚀 Deployment Richtlijnen ### Omgevingsvariabelen ```bash # JWT Configuratie JWT_SECRET=uw_sterke_geheim_hier JWT_EXPIRES_IN=24h # Rol Configuratie DEFAULT_ROLE=Viewer ADMIN_EMAILS=admin@voorbeeld.nl,super@voorbeeld.nl ``` ### Health Checks ```yaml Beveiligde health endpoints: - /health/basic: Openbaar toegankelijk - /health/detailed: Alleen Admin/Editor - /health/system: Alleen Admin ``` --- Deze documentatie biedt ontwikkelaars een compleet framework voor het implementeren van veilige gebruikersautorisatie in MijnService API. Voor aanvullende vragen of security reviews, raadpleeg het beveiligingsteam.