CS:Metadata Aanbieden aan Koppelpunt

Kennisnet biedt een koppelpunt voor catalogusinformatie die volgens het 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

Elk uur 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:

{{Base Url}}/v1/products

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.

  /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

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.'

  /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"

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.