Brontekst bekijken van CS:Metadata Aanbieden aan Koppelpunt

Kennisnet biedt een koppelpunt voor catalogusinformatie die volgens het [https://edu-v.atlassian.net/wiki/spaces/AFSPRAKENS/pages/21692475/Catalogue+API Edu-V afsprakenstelsel] wordt uitgewisseld. Op deze pagina wordt gespecificeerd hoe partijen metadata kunnen aanbieden aan dit geaggregeerd endpoint.

== Aanleveren catalogusinformatie ==
=== Aansluitproces ===
Koppelpunt Edu-v Harvester kan alleen aanbieders aansluiten die zich via Edu-V hebben geregistreerd voor deelname.
=== Authenticatie ===
Als de aanbieder van de Catalogue API kiest voor authenticatie ondersteunen wij Base OAuth 2.0 authenticatie op basis van ClientId en Private Key JWT (JSON Web Token) en JWKS URL (public key).

Wij verwachten van de aanbieder dat hij het volgende levert: Client Id, Client Secret en Token Url.

Aanbieder kan er ook voor kiezen om geen authenticatie te implementeren. 

=== Get All Products ===
Elke 10 minuten stuurt de Koppelpunt Edu-v Harvester een 'Get All Products'-request naar alle verbonden API-endpoints.

==== Versie ====
We verwachten dat de API endpoint-URL op de volgende manier wordt gemaakt:
<syntaxhighlight lang="xml">
{{Base Url}}/v1/products
</syntaxhighlight>

==== Pagineren ====
In het Edu-V Afsprakenstelsel kunnen aanbieders paginering toepassen om de prestaties van hun interfaces te verbeteren. OpenAPI 3 specificeert geen standaardmanier om paginering te implementeren. 

We hebben ervoor gekozen om de methode te implementeren die in versie 0.9.0 werd beschreven.

<syntaxhighlight lang="xml">
  /products:
    parameters:
      - schema:
          type: integer
        name: start
        in: query
        description: 'Start point for pagination of results, defaults to 0,'
        examples:
          default:
            value: 0
            summary: The start point for pagination
      - schema:
          type: integer
          maximum: 100
        in: query
        name: limit
        description: 'Limit of number of results returned by page, defaults to 20 with max 100.'
        examples:
          default:
            value: 20
            summary: The default value if none is provided
          max:
            value: 100
            summary: The largest recommended page size
</syntaxhighlight>

In het geval dat de server de parameters volledig negeert en alle producten retourneert, kunnen we alle aangeleverde records opslaan en verwerken.

==== Incrementele harvesting ====
OpenAPI 3 specificeert geen standaardimplementatie voor een "since"-parameter en definieert niet of deze moet worden geïmplementeerd als > (groter dan) of >= (groter dan of gelijk aan). 

Wij verwachten het volgende response: 'Retourneer alle producten die vanaf deze datum zijn toegevoegd of gewijzigd, inclusief de opgegeven datum.'
<syntaxhighlight lang="xml">
  /products:
    parameters:
      - schema:
          type: string
          format: date-time
        in: query
        name: since
        required: false
        description: 'Request all products modified after the specified timestamp. Format: Conform openapi in ZULU time as specified in RFC 3339, section 5.6'
        example: "2017-07-21T17:32:28Z"
</syntaxhighlight>

Incrementele harvesting wordt momenteel niet gebruikt, maar de verwachting is dat dit in de toekomst de standaardmanier zal zijn om wijzigingen te verzamelen.

==== Validatie ====
Koppelpunt Edu-v Harvester verzamelt momenteel alleen records en schrijft ze naar een geaggregeerd endpoint. Er is momenteel geen sprake van recordvalidatie. De aanbieder wordt geacht de velden te vullen conform het Edu-V afsprakenstelsel. 

=== Get Product by ID ===
Voor Koppelpunt Edu-v Harvester, dat een geaggregeerd endpoint moet maken, hebben we niet de mogelijkheid geïmplementeerd om individuele producten te harvesten.