Bij onze klanten geven wij prioriteit aan de bruikbaarheid van onze API’s. Om dit te bereiken, schrijven wij wat wij een “Gedetailleerd Ontwerp” pagina noemen voor elke API die wij ontwikkelen. Deze Gedetailleerd Ontwerp pagina wordt altijd gegenereerd vanuit ons sjabloon met 8 secties:
- Revisiegeschiedenis
- Hoofddoelstelling van de API
- Lijst van endpoints
- Gedetailleerd Ontwerp per endpoint
- Artefactsamenvatting
- API Ontwerpbeslissingen
- Oplossingsontwerp beslissingen
- Postman collectie
1. Revisiegeschiedenis
De revisiegeschiedenis is een eenvoudig tabelelement waar wij bijhouden welke ontwikkelaar welke secties heeft toegevoegd aan het Gedetailleerd Ontwerp:
| Datum | Versie | Beschrijving | Auteur |
|---|---|---|---|
| 01.02.2024 | 1.0 | Initiële versie met: • POST /idoc | Jani swinnen |
Revisiegeschiedenis tabel
Wij houden de datum bij waarop het endpoint werd toegevoegd, evenals een korte beschrijving van de wijzigingen en de persoon die deze wijzigingen heeft aangebracht. Ten slotte geven wij elke revisie een versienummer zodat wij gemakkelijk kunnen zien in welke volgorde de wijzigingen zijn aangebracht.
2. Hoofddoelstelling van de API
In deze sectie schetsen wij de hoofddoelstelling voor de API, wat een kernconceptis van Mulesoft’s API-led connectivity benadering. Door een hoofddoelstelling voor de API te definiëren kunnen wij het gebruik van de API gericht houden op dat doel en gemakkelijk bepalen of een nieuwe functionaliteit binnen de scope van dat doel zou vallen.
Doelstelling De API zal verantwoordelijk zijn voor het ontvangen van verzoeken van SAP ERP Systeem dat verschillende soorten informatie wil verkrijgen
3. Lijst van endpoints
Vervolgens sommen wij alle geïmplementeerde endpoints op zodat de eindgebruiker gemakkelijk een overzicht kan krijgen van de beschikbare endpoints in deze API.
De API heeft de volgende endpoints geïmplementeerd: • POST /idocrouter • POST /sdfc/attachmenthandler • POST /products • POST /vendor/pricing
Lijst van endpoints voor een API
4. Gedetailleerd ontwerp
Na de algemene documentatie, hierboven beschreven, voegen wij een gedetailleerd ontwerp toe voor elk endpoint. Elk gedetailleerd ontwerp bestaat uit de volgende onderdelen:
- Beschrijving
- Procesdiagram
- Processtappen
- Sequentiediagram
Beschrijving
De beschrijvingssectie van een gedetailleerd ontwerp bevat de endpoint URI en HTTP Methode evenals een korte beschrijving van de functionaliteit van dat endpoint.
GET /events/installation Bevraag installatie-events voor de gewenste producten binnen het gespecificeerde tijdsbereik
Beschrijvingssectie van het gedetailleerd ontwerp
Procesdiagram
De procesdiagramsectie bestaat uit een procesdiagram dat visualiseert hoe het endpoint functioneert. Wij ontwerpen dit vaak met behulp van de Gliffy add-on voor Confluence. Elke stap in dit diagram krijgt een nummer, waarnaar wij zullen verwijzen in de volgende sectie van het gedetailleerd ontwerp.
Processtappen
Na het diagram beschrijven wij elke stap in meer detail. In deze sectie voegen wij ook de mappingspecificaties toe die wij hebben gebruikt voor Dataweave transformaties, evenals de URI’s voor mogelijke aanroepen naar andere API’s.
Sequentiediagram
In het laatste deel van het gedetailleerd ontwerp nemen wij een Sequentiediagram op – ook ontworpen met Gliffy – dat de complete aanroepsequentie binnen onze API architectuur visualiseert. Dit stelt de eindgebruikers in staat om te zien hoe de aanroepen door de API architectuur gaan.
5. Artefactsamenvatting
Na de gedetailleerde ontwerpen is er een laatste sectie met enkele laatste details. Beginnend met de artefactsamenvatting, die bestaat uit het volgende:
- Een link naar het API specificatieproject op het Mulesoft Design Center. Dit stelt ons in staat om snel de bijbehorende RAML specificatie voor elk van de API’s te vinden.
- Een link naar het Exchange asset voor de API’s, evenals de naam van het Mule Project.
- Een link naar de GitHub repository van de API en de Mule versie waarin de API werd ontwikkeld.
- Een lijst van de applicatienamen voor elk van onze omgevingen.
6. API Ontwerpbeslissing
De API ontwerpbeslissing sectie beschrijft zowel de API ontwerpconventies die werden gebruikt als de beveiligingsschema’s die in gebruik zijn. De beveiligingssectie kan behoorlijk verschillen van systeem tot systeem. Voor interne communicatie gebruiken wij vaak Mutual TLS, maar voor externe systemen hangt het af van wat die systemen ondersteunen.
7. Oplossingsontwerp Beslissingen
De op één na laatste sectie behandelt de beslissingen die zijn genomen tijdens het voorbereiden van het oplossingsontwerp.
- Wij beschrijven de ontwerppatronen die in deze API worden gebruikt, bijvoorbeeld HTTP synchrone patroon, Messaging asynchrone patroon, enz.
- Wij maken een lijst van alle eigenschappen die binnen het project zijn gedefinieerd. Dit zijn vaak de verbindingseigenschappen voor verbinding met andere API’s.
- Wij doen de foutpuntanalyse, waarbij wij de verschillende manieren waarop de API kan falen analyseren en voorspellen. Dit is een goede start bij het proberen om fouten in de API op te lossen.
- Wij hebben een sectie voor mogelijke waarschuwingen die uit het project worden gegenereerd.
- Wij sommen de loggingstrategie op die in het project wordt gebruikt.
8. Postman Collectie
En ten slotte, als onderdeel van het gedetailleerd ontwerp voor elke API, nemen wij een export van de Postman collectie op, om andere ontwikkelaars te helpen bij het oplossen van problemen door hen de testdata en verzoeken te laten importeren die tijdens de ontwikkeling zijn gebruikt. Deze collectie bevat vaak de verzoeken naar de lokale omgeving bij het debuggen/uitvoeren van de applicatie, en de verzoeken naar de DEV omgeving op Cloudhub.
Bent u met ons mee?
Geïnteresseerd om zelf op deze manier te werken? Of gelooft u dat onze werkwijze u als bedrijf zou kunnen helpen? Neem contact op!
