Hoe je Open API-bestanden effectief valideert met WSO2 API Manager

De OpenAPI Specificatie (OAS) is een cruciaal aspect van API-first design. Het behouden van nauwkeurige en kwalitatieve OpenAPI-bestanden is essentieel voor een duurzame API-ontwikkelingspraktijk. In dit artikel bespreken we verschillende aspecten van OpenAPI-bestandsvalidatie en de tools die hiervoor kunnen worden gebruikt. We richten ons voornamelijk op WSO2 API Manager 4.2.0, die nu een ingebouwde methode heeft om OpenAPI-bestanden te valideren zonder externe tools te hoeven gebruiken. Naast de standaard OAS-regels, bespreken we ook hoe je je eigen validatieregels kunt schrijven om je OpenAPI-bestanden te valideren zodat ze voldoen aan de standaarden en beleidsregels van je organisatie. Aan het einde behandelen we ook enkele typische OpenAPI-validatievereisten met enkele voorbeeldregels op maat. Ik geloof dat dit artikel waardevolle aanvullingen zal bieden voor je API-ontwikkelingspraktijken.

Belang van de OpenAPI Specificatie (OAS) in API-first design

De OpenAPI Specification (OAS) is een beschrijvingsformaat voor REST API’s en webhooks. Het was voorheen bekend als Swagger. Het stelt ons in staat om volledige API’s te beschrijven, inclusief beschikbare eindpunten/operaties, input/output parameters en onder meer authenticatiemethoden. Daarom is het bij gebruik van OAS in API-ontwikkeling cruciaal om de nauwkeurigheid en kwaliteit van OpenAPI-bestanden te handhaven, omdat de hele API-ontwikkelingscyclus ervan afhangt. Er moet dus een goede en eenvoudige manier zijn om deze OpenAPI-bestanden te valideren.

Stappen voor het valideren van Open API-bestanden

Bij OAS-validatie zijn er twee aspecten die je wilt valideren:

1. Open API-bestanden moeten worden gevalideerd tegen standaard OAS-regels.
2. Open API-bestanden kunnen ook worden gevalideerd tegen aangepaste regels, bijvoorbeeld organisatie-specifieke regels.

Standaard OAS-regels: Zorg voor nauwkeurigheid in Open API-bestanden

Dit is een belangrijke stap om ervoor te zorgen dat Open API-bestanden nauwkeurig zijn, de best practices volgen en voldoen aan de vastgestelde OAS-standaarden. Er zijn tools beschikbaar om OpenAPI-bestanden te valideren tegen de OpenAPI Specificatie. Spectral en Swagger-Editor zijn twee van zulke populaire tools.

Hier zijn enkele belangrijke OAS-regels die doorgaans onder deze categorie worden gevalideerd:

• Bestandssyntaxisvalidatie
  • Zorg ervoor dat het Open API-bestand de juiste JSON/YAML-opmaak heeft en geen syntaxisfouten bevat.
• Schema-validatie
  • Verificatie van de juistheid van schemastructuren
  • Gegevenssoorten en objecteigenschappen zijn gedeclareerd binnen de OpenAPI-specificatie.
• Parameter-validatie
  • Ensure the query parameters, path parameters, headers, and cookies are correctly defined with data types, descriptions, and validations.
• Onduidelijke API-resources
  • Zorg ervoor dat er geen conflicterende API-resources zijn, bijvoorbeeld `/pets/{name}` en `/pets/{id}`.
• Beveiligingsdefinities
  • Verifiëren van de nauwkeurigheid en volledigheid van beveiligingsdefinities.
• Succesvolle API-antwoorden
  • Zorg ervoor dat elke API-resource ten minste één succesvol antwoord heeft (2xx of 3xx).
• Versiebeheer en compatibiliteit
  • Zorg ervoor dat de API-definitie voldoet aan een specifieke versie van de OpenAPI Specificatie en achterwaartse of voorwaartse compatibiliteit behoudt.
• Foutafhandeling
  • Validatie van foutreacties, statuscodes en foutberichtstructuren gedefinieerd binnen de API-specificatie.
• API-voorbeelden
  • Zorg ervoor dat de gegeven API-aanvraag/antwoord-payloadvoorbeelden geldig zijn volgens de API-definitie.

Totdat je je OpenAPI-bestanden valideert tegen al deze standaardregels en foutvrij maakt, zijn ze geen echte OpenAPI-bestanden, maar slechts tekstbestanden. Door een OpenAPI-validatietool te gebruiken om deze standaardregels te valideren, kun je inconsistenties in de vroege stadia van de API-ontwikkelingscyclus opsporen en ze omzetten in echte en nauwkeurige OpenAPI-bestanden voordat je deze gebruikt om echte API’s te bouwen.

Consistentie creëren: Aangepaste linterregels voor Open API-validatie

Organisaties en ontwikkelingsteams hebben meestal hun eigen standaarden naast de industriestandaarden. Dat geldt ook voor de API’s. Wanneer een organisatie API’s wil publiceren, willen ze misschien dat API-ontwikkelaars zich houden aan bepaalde regels die zijn gebaseerd op de interne standaarden en beleidsregels van de organisatie. Bijvoorbeeld API-pad- en parametersnaamgevingsconventies, beschikbaarheid van API-voorbeelden en bepaalde beperkingen voor API-informatie. Om aan dergelijke vereisten te voldoen, kunnen aangepaste linterregels worden gebruikt om OpenAPI-bestanden te valideren. Niet alle OpenAPI-validatietools ondersteunen echter aangepaste linterregels. Spectral is een van die geweldige tools die zowel standaard OAS-regels als aangepaste linterregels ondersteunt.

Gebruikmaken van WSO2 API Manager voor Open API-bestanden

Als je een gebruiker bent van WSO2 API Manager, heb je het geluk dat je de volledige functionaliteit van de Spectral linter-tool binnen WSO2 API Manager hebt, en hoef je je geen zorgen meer te maken over het gebruik van een externe tool alleen om OpenAPI-bestanden te valideren. Sinds versie 4.2.0 is Spectral ingebed in WSO2 API Manager met wat extra UI-ondersteuning.

Nu, wanneer je een OpenAPI-bestand importeert in WSO2 API Manager, valideert het standaard het bestand tegen standaard OAS-regels en toont het je een overzicht van fouten, waarschuwingen, informatie en hints zoals hieronder getoond.

Je kunt de sectie Linter Resultaten uitbreiden en meer details lezen over elke fout/waarschuwing.

Op dit punt heb je twee opties:

1. Het originele OpenAPI-bestand bijwerken en opnieuw importeren om de API te maken.
2. Doorgaan met het maken van de API met het huidige OpenAPI-bestand en de API later aanpassen om de fouten te corrigeren.

Optie 2 kan een geschikte keuze zijn als je om een of andere reden het originele OpenAPI-bestand niet kunt bijwerken, bijvoorbeeld als je niet de eigenaar ervan bent. Aan de andere kant doorbreekt het je API-creatieflow niet. Het laat je gewoon doorgaan. Als je deze optie kiest, kun je de linterfouten corrigeren nadat je de API hebt gemaakt. Hiervoor ga je naar de sectie API Definitie en vervolgens Bewerk de API-definitie.

Als je vervolgens overschakelt naar de “Linter” weergave aan de rechterkant, kun je de door Spectral gedetecteerde fouten en waarschuwingen zien. Wanneer je fouten/waarschuwingen in het linker paneel oplost, verdwijnt het relevante fout-/waarschuwingsbericht aan de rechterkant.

Zodra je tevreden bent met het resultaat, kun je de API-definitie opslaan en doorgaan met de rest van je API-levenscyclus.

Aangepaste linterregels configureren in WSO2 API Manager

Zoals eerder besproken, is een van de krachtigste functies van Spectral het vermogen om aangepaste regels te definiëren. Dat kun je ook doen binnen de WSO2 API Manager. Het biedt je extra UI’s om dit proces soepel te laten verlopen. Hier is hoe je een nieuwe aangepaste regel kunt toevoegen.

1. Ga naar het beheerdersportaal. Klik in het linker zijpaneel op Geavanceerd onder Instellingen. Je wordt dan doorgestuurd naar de editor “Geavanceerde configuraties“.

2. Hier moet je een nieuwe sleutel “LinterCustomRules” toevoegen aan dit configuratiebestand. (De standaardconfiguratie heeft geen sectie “LinterCustomRules.”) Binnen de sectie “LinterCustomRules” voeg je een nieuwe sleutel “rules” toe zoals weergegeven in de onderstaande afbeelding.

3. Binnen deze sectie kun je een willekeurig aantal aangepaste regels definiëren met aangepaste regelsleutels. Hier is een voorbeeldregel die valideert of het contactemail van de API een Yenlo-email is. (Later meer over deze regel.)

4. Nadat je de bovenstaande regel hebt opgeslagen, zie je eventuele nieuwe fouten die door de nieuwe regel zijn geïdentificeerd in de sectie API definitie van het Publisher-portaal zoals deze.

Geavanceerde aangepaste linterregels voor Open API-validatie verkennen

Een aangepaste linterregel heeft verschillende delen. Laten we eens kijken wat elk van hen betekent:

• Beschrijving: Dit beschrijft de regel.
• Gegeven: Dit specificeert welk deel van het OpenAPI-bestand we willen valideren.
• Dan: Dit specificeert hoe het moet worden gevalideerd. In deze sectie kunnen we specificeren wat moet worden gevalideerd met welke functie. We kunnen hier ook meer functie-opties specificeren.
• Ernst: Dit kan een van de volgende zijn: error, warn, info, hint en off. Dit specificeert de ernst van de fout.
• Bericht: Dit is een optioneel bericht dat wordt weergegeven bij gedetecteerde fouten.

Je kunt meer lezen over deze opties in de officiële documentatie van Spectral.

Illustratieve voorbeelden van aangepaste regels voor Open API-validatie

Laten we nu eens kijken naar enkele aangepaste regels die nuttig kunnen zijn in een typisch API-ontwikkelingsproces.

1. Laten we beginnen met het eerder genoemde emailvoorbeeld.

"company-info-email-rule": {
    "description": "Contact email address must be a Yenlo email.",
    "given": "$",
    "severity": "error",
    "then": {
        "field": "info.contact.email",
        "function": "pattern",
        "functionOptions": {
            "match": "^[a-z]+@yenlo.com$"
        }
    }
 }

Deze regel definieert dat het contactemail van de infosectie moet voldoen aan de regex `^[a-z]+@yenlo.com$`, wat betekent dat het een Yenlo-email moet zijn. Hier wordt de “pattern”-functie gebruikt met de “match”-optie.

2. Alle POST API-resources moeten een voorbeeldaanvraag hebben.

"post-request-example": {
    "description": "All POST application/json requests must have examples.",
    "given": "$.paths.*.post.requestBody.content.application/json",
    "severity": "error",
    "then": {
        "field": "examples",
        "function": "truthy"
    }
 }

Deze regel definieert dat als er POST-aanvraaglichamen zijn met application/json content-type, ze een voorbeeld moeten hebben. Hier betekent de functie “truthy” dat iets (het veld “examples” in dit geval) moet bestaan. De tegenovergestelde functie hiervan is de “falsy”-functie die ervoor zorgt dat iets niet bestaat.

3. Alle schema-eigenschappen moeten in camelCase zijn.

"model-properties-camelcase": {
    "description": "All schema properties must be in camelCase.",
    "given": "$.components.schemas.*.*.~",
    "severity": "warn",
    "then": {
        "function": "casing",
        "functionOptions": {
           "type": "camel"
        }
    }
 }

Deze regel gebruikt de “casing”-functie met zijn optie “type”. Spectral ondersteunt de volgende “cases” standaard:

• camel (bijvoorbeeld: veryLongName)
• pascal (bijvoorbeeld: VeryLongName)
• kebab (bijvoorbeeld: very-long-name)
• cobol (bijvoorbeeld: VERY-LONG-NAME)
• snake (bijvoorbeeld: very_long_name)
• macro (bijvoorbeeld: VERY_LONG_NAME)

4. Alle tags moeten in alfabetische volgorde staan.

"openapi-tags-alphabetical": {
    "description": "OpenAPI objects should have tags in the alphabetical order.",
    "given": "$",
    "severity": "warnn",
    "then": {
        "field": "tags",
        "function": "alphabetical",
        "functionOptions": {
           "keyedBy": "name"
        }
    }
 }

Hier gebruikt de regel de “alphabetical”-functie die ervoor zorgt dat gegeven array-elementen of objecteigenschappen in alfabetische volgorde worden gesorteerd door een sleutel gegeven door de optie “keyedBy”.

5. Tags mogen alleen afkomstig zijn van een vooraf gedefinieerde lijst.

"whitelisted-tags": {
    "description": "Tags should be coming from the given list of tags.",
    "given": "$.paths.*",
    "severity": "error",
    "then": {
        "field": "tags",
        "function": "enumeration",
        "functionOptions": {
            "values": [
                "users",
                "articles",
                "categories"
            ]
        }
    }
 }

Deze regel gebruikt de “enumeration”-functie die kan worden gebruikt om een waarde te beperken tot altijd een van de gegeven waarden te zijn.

6. Alle operaties moeten ten minste één tag hebben maar niet meer dan drie.

"operation-singular-tag": {
    "description": "Operations must have between 1 and 3 types.",
    "given": "$.paths.*",
    "severity": "error",
    "then": {
        "field": "tags",
        "function": "length",
        "functionOptions": {
            "max": 3,
            "min": 1
        }
    }
 }

Deze regel gebruikt de “length”-functie die min– en max-opties heeft.

Op dezelfde manier kun je complexere aangepaste regels definiëren met behulp van verschillende Spectral kernfuncties. Je kunt hier meer over lezen.

Duurzame API-ontwikkelingspraktijk opbouwen

In dit artikel hebben we besproken wat de OpenAPI Specificatie is en waarom we deze nodig hebben. We hebben de twee aspecten van OpenAPI-validatie en de tools die deze ondersteunen besproken. We hebben specifiek gesproken over Spectral, dat nu is geïntegreerd met WSO2 API Manager, en hoe je het kunt gebruiken om je OpenAPI-bestanden te valideren tegen standaard OAS-regels en aangepaste linterregels. We zijn dieper ingegaan op aangepaste regels en hebben enkele typische validatie use-cases met voorbeeldregels behandeld. Dus als je een API-ontwikkelaar, een API-producteigenaar of iemand bent die werkt in de API-ontwikkelingsruimte, geloof ik dat wat we in dit artikel hebben besproken nuttig voor je kan zijn om een duurzame API-ontwikkelingspraktijk in je organisatie te handhaven.