Natuurlijk! Hier is een voorstel voor een gedetailleerde API-documentatie voor jouw Sanity CMS-project, inclusief de aspecten GET /api/v1/posts, OAuth2 en XML. Daarnaast geef ik tips om de documentatie duidelijk en nuttig te maken voor ontwikkelaars. --- # API-Documentatie voor Sanity CMS ## Overzicht Deze API biedt toegang tot de blogposts en andere content binnen ons Sanity CMS. Alle endpoints ondersteunen standaard REST-werkwijzen en authenticatie via OAuth2. De API ondersteunt zowel JSON- als XML-formaat voor gegevensuitwisseling. --- ## 1. Endpoints ### 1.1 GET /api/v1/posts **Beschrijving:** Haalt een lijst op van alle blogposts. **URL:** `/api/v1/posts` **Method:** `GET` **Vraagparameters:** - `limit` (optioneel): Het maximum aantal posts dat wordt teruggegeven. Standaard 10. - `author` (optioneel): Filter posts op auteur. - `category` (optioneel): Filter posts op categorie. - `format` (optioneel): Geeft het response formaat terug. Kan `json` of `xml` zijn. Standaard `json`. **Antwoord:** - **JSON-formaat:** ```json { "posts": [ { "id": "abc123", "title": "Voorbeeld Post", "author": "Jan Jansen", "category": "Technologie", "published_at": "2024-04-25T10:00:00Z", "content": "De inhoud van de post..." } ] } ``` - **XML-formaat:** ```xml <posts> <post> <id>abc123</id> <title>Voorbeeld Post</title> <author>Jan Jansen</author> <category>Technologie</category> <published_at>2024-04-25T10:00:00Z</published_at> <content>De inhoud van de post...</content> </post> </posts> ``` --- ## 2. Authenticatie: OAuth2 ### 2.1 OAuth2 Authenticatie - **Type:** OAuth 2.0 Authorization Code Grant - **Scope:** `read:posts` ### 2.2 Authenticatieproces 1. **Gebruiker autoriseert:** De ontwikkelaar krijgt een autorisatie-URL om toegang te verlenen. 2. **Token verkrijgen:** Na autorisatie ontvangt de ontwikkelaar een access token. 3. **Toegang tot API:** Het access token wordt meegegeven in de header: ```http Authorization: Bearer {access_token} ``` ### 2.3 Token vervaldatum Tokens zijn geldig voor 1 uur en moeten verversd worden via de refresh token. --- ## 3. Response formaten ### 3.1 JSON - Standaard response-formaat. - Goed leesbaar en makkelijk te parseren. ### 3.2 XML - Optioneel te specificeren via de `format` queryparameter (`format=xml`). - Gebruiksvriendelijk voor systemen die XML prefereren. --- ## 4. Hoe zorg je voor duidelijke en nuttige documentatie? ### Tips: - **Gebruik duidelijke taal:** Vermijd jargon en leg technische termen uit. - **Voorzie voorbeelden:** Geef concrete voorbeeldverzoeken en voorbeeldantwoorden in JSON en XML. - **Documenteer queryparameters:** Leg uit wat elke parameter doet en welke standaardwaarden gelden. - **Beschrijf foutcodes:** Geef aan welke foutmeldingen kunnen voorkomen en hoe deze te interpreteren. - **Leg authenticatie uit:** Beschrijf stap voor stap hoe OAuth2 werkt en hoe ontwikkelaars tokens kunnen verkrijgen. - **Gebruik overzichtelijke structuur:** Maak gebruik van koppen, lijsten en tabellen voor overzicht. - **Voeg statuscodes toe:** Leg uit wat de verschillende HTTP-statuscodes betekenen voor elk endpoint. - **Interactiviteit:** Overweeg een interactieve API-doc zoals Swagger of Postman zodat ontwikkelaars direct kunnen testen. --- Met deze aanpak zorg je dat je API-documentatie niet alleen technisch volledig is, maar ook gebruiksvriendelijk en gemakkelijk te begrijpen voor ontwikkelaars. --- Heeft u nog specifieke wensen of vragen?

Zeker! Hier is een gedetailleerde API-documentatie voor je Sanity CMS-project in het Nederlands: # Sanity CMS API Documentatie v1.0 ## 📋 Inhoudsopgave 1. [Authenticatie](#authenticatie) 2. [Posts Endpoint](#posts-endpoint) 3. [XML Ondersteuning](#xml-ondersteuning) 4. [Best Practices](#best-practices) ## 🔐 Authenticatie ### OAuth2 Implementatie ```javascript // Authenticatie flow voorbeeld const oauthConfig = { authorizationURL: "https://api.jouwproject.sanity.io/v1/oauth/authorize", tokenURL: "https://api.jouwproject.sanity.io/v1/oauth/token", clientId: "JOUW_CLIENT_ID", clientSecret: "JOUW_CLIENT_SECRET", callbackURL: "https://jouwdomein.nl/auth/callback" }; ``` **Scopes:** - `posts.read` - Leesrechten voor posts - `posts.write` - Schrijfrechten voor posts - `posts.manage` - Beheerrechten voor posts ## 📝 Posts Endpoint ### GET /api/v1/posts **Beschrijving:** Haalt een lijst van blogposts op uit Sanity CMS **Parameters:** | Parameter | Type | Verplicht | Beschrijving | |-----------|------|-----------|--------------| | `limit` | integer | Nee | Aantal posts (standaard: 20, max: 100) | | `offset` | integer | Nee | Paginering offset (standaard: 0) | | `category` | string | Nee | Filter op categorie | | `status` | string | Nee | Filter op status ('published', 'draft') | | `format` | string | Nee | Response formaat ('json', 'xml') | **Request Voorbeeld:** ```http GET /api/v1/posts?limit=10&offset=0&category=tech&status=published&format=json Authorization: Bearer {access_token} ``` **Success Response (200):** ```json { "status": "success", "data": { "posts": [ { "id": "post-123", "title": "API Documentatie Tips", "slug": "api-documentatie-tips", "content": "Volledige inhoud...", "excerpt": "Korte samenvatting...", "author": { "name": "Jan Jansen", "email": "jan@voorbeeld.nl" }, "categories": ["tech", "documentatie"], "published_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-16T14:22:00Z" } ], "pagination": { "total": 150, "limit": 10, "offset": 0, "has_more": true } } } ``` **Error Responses:** - `401 Unauthorized` - Ongeldig of verlopen token - `403 Forbidden` - Onvoldoende rechten - `500 Internal Server Error` - Server fout ## 📄 XML Ondersteuning ### XML Response Formaat **Request:** ```http GET /api/v1/posts?format=xml&limit=5 Authorization: Bearer {access_token} ``` **Response:** ```xml <?xml version="1.0" encoding="UTF-8"?> <response> <status>success</status> <data> <posts> <post> <id>post-123</id> <title>API Documentatie Tips</title> <slug>api-documentatie-tips</slug> <content>Volledige inhoud...</content> <excerpt>Korte samenvatting...</excerpt> <author> <name>Jan Jansen</name> <email>jan@voorbeeld.nl</email> </author> <categories> <category>tech</category> <category>documentatie</category> </categories> <published_at>2024-01-15T10:30:00Z</published_at> <updated_at>2024-01-16T14:22:00Z</updated_at> </post> </posts> <pagination> <total>150</total> <limit>5</limit> <offset>0</offset> <has_more>true</has_more> </pagination> </data> </response> ``` ## 💡 Best Practices voor Documentatie ### 1. **Gebruik Duidelijke Voorbeelden** - Toon complete request/response cycli - Includeer codevoorbeelden in meerdere programmeertalen - Toon zowel succes als fout scenarios ### 2. **Interactive Documentatie** Overweeg tools zoals: - **Swagger/OpenAPI** voor interactieve docs - **Postman Collection** voor testen - **Sanity Studio** integratie voor content beheerders ### 3. **Foutafhandeling Documenteren** ```json { "status": "error", "code": "AUTH_001", "message": "Ongeldig access token", "details": "Het provided token is verlopen of ongeldig" } ``` ### 4. **Versiebeheer** - Gebruik semantische versienummers (v1, v2) - Documenteer breaking changes - Ondersteun deprecated endpoints tijdelijk ### 5. **Rate Limiting** ```http X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1642165200 ``` ### 6. **Sanity-specifieke Tips** - Gebruik GROQ queries in je endpoints - Documenteer custom content types - Includeer Sanity CLI commands voor setup ## 🚀 Snelle Start 1. **Registreer applicatie** in Sanity Management Console 2. **Configureer OAuth2** credentials 3. **Test endpoints** met Postman of curl 4. **Implementeer error handling** in je applicatie 5. **Monitor usage** via Sanity Dashboard **curl Voorbeeld:** ```bash curl -X GET \ "https://api.jouwproject.sanity.io/v1/posts?limit=5&format=json" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" ``` Deze documentatie biedt een solide basis voor ontwikkelaars om met je Sanity CMS API te werken. Zorg ervoor dat je de documentatie regelmatig bijwerkt naarmate de API evolueert!