Requirements Developer Portal

[nielskorporaal]

De volgende requirements zijn aan de orde bij het maken van de keuze voor een developer portal. Niet alle requirements zijn even belangrijk, hieronder volgt in willekeurige volgorde een opsomming. Aanvullingen zijn welkom.

1. Meertalige ondersteuning (Nederlands, Engels)
2. RedocLy-documentatie
   • embedded redoc docs
3. Out-of-the-box API-voorbeelden (try-out)
   • In-memory database
   • PostgreSQL-database
   • API mocks aanbieden
4. Fields-tool voor het opstellen van requests
   • dynamisch requests genereren
   • validatie verplichte/optionele velden
   • ondersteuning voor authenticatie tokens (bijv: OAuth)
5. How-to guides (zie Diátaxis) bijvoorbeeld:
   • Hoe kan ik bewoners van een adres tijdens een bepaalde periode opvragen?
   • Hoe kan ik de aanschrijfwijze van personen opvragen?
   • Hoe kan ik de gezagsrelaties van personen opvragen?
6. Referenties (zie Diátaxis) bijvoorbeeld:
   • OpenAPI-specificaties
   • Logisch ontwerp
   • ADR's (Architectural Decision Records)
7. Release notes
   • koppeling met git-repo's
8. Ondersteuning voor een design-first aanpak
   • genereren van PR's op basis van aangepaste of voorgestelde wijzigingen in API-specificaties
9. Zoeken in de documentatie
   • Handig om snel relevante handleidingen, referenties en voorbeelden te vinden
10. Authenticatie
    • API-keys
    • OAuth 2.0
    • Instructie nieuwe aansluiters

[FrozenSync]

Zijn er requirements rondom pricing?

[nielskorporaal]

We hebben in het ontwikkelteam een aantal opties overwogen en hieruit zijn twee alternatieve oplossingen gekomen.

1. Developer portal op basis van een static site generator (SSG) stack en Redoc viewer

Deze oplossing sluit aan bij wat we nu al hebben, we kunnen dit eventueel zelf uitbreiden met zaken zoals meertaligheid, maar ook componenten aanbieden om bijvoorbeeld de fields tool zelf te beheren. We kunnen dan de Redoc-viewer zoals nu ook blijven gebruiken. We zouden zelfs ondersteuning bieden voor extra markdown, preview van de te publiceren content en asciidoc.

Voordelen

• open source
• gratis
• de mogelijkheid om eigen github actions schrijven (geautomatiseerd specificaties uit verschillende repos halen)
• ondersteuning voor asciiDoc mogelijk

Nadelen

• implementatie is tijdintensief
• dev portal bouwen is geen core domain
• zelf zoekfunctionaliteit inbouwen

2. Developer portal op basis van Realm (Redoc + Revel + Reef)

Deze stack biedt een compleet pakket aan tools om API's te specificeren, documenteren en beheren en biedt ondersteuning voor autorisatie. Dit is veruit de makkelijkste oplossing en hiermee kunnen we gebruik maken van Redoc voor het beheren van de OpenAPI specificaties, Revel voor de Markdown en Markdoc content + localisatie en Reef voor eventuele API catalogs en dynamische client registraties (en autorisatie)

Voordelen

• ready-to-use voorgedefinieerde functionaliteit waar we gebruik van kunnen maken zoals:
  • git integratie
  • previewer
  • try-out functionaliteit
  • het opzetten van documentatie is makkelijker (cms)
• Reef (dynamic client API registration)
• out-of-the-box ondersteuning voor meertaligheid (l8n)
• zoeken in documentatie
• betere ondersteuning design-first API ontwikkeling (redoc UI heeft dit al)

Nadelen

• kosten (PRO features zijn ca. $9 - $25 per seat) https://redocly.com/pricing

Beide oplossingen ondersteunen

• preview
• redoc viewer
• custom themes
• fields tool
• release notes
• how-tos

[MelvLee]

Waarom is bij optie 1 de integratie met SP of ICTU nodig voor realistische try-outs?

[FrozenSync]

Ik zou de optie titels hernoemen en een aantal punten toevoegen.

1. Developer portal op basis van een static site generator (SSG) stack en Redoc viewer

... open source en gratis.

2. Developer portal op basis van Realm (Redoc + Revel + Reef)

... proprietary en betaald.

In optie 1 wordt "integratie met SP of ICTU" genoemd. Dit moet ook gebeuren in optie 2. In principe zijn beide opties verantwoordelijk voor de frontend. Voor realistische try-outs heb je een backend nodig die draait in een cloud omgeving (SP of ICTU); los van de frontend dus.

[MelvLee]

wat pros en cons toevoegen aan de opties lijkt mij handig. We hebben dan een overzicht van waar we wel hebben over nagedacht en waarover (nog) niet

[MelvLee]

Gisteren gaf ik bij optie 1 als cons dat je wijzigingen niet kan previewen. Ik heb nu een GH action gevonden waarmee het wel zou kunnen. Zie: https://github.com/marketplace/actions/deploy-pr-preview

[FrozenSync]

Open source alternatieven:
https://antora.org/
Static Site Generators (SSGs) zoals https://jekyllrb.com/, https://gohugo.io/, https://www.11ty.dev/, etc.