Overzicht

SURFeduhub is een gecentraliseerd platform waarmee Data afnemers toegang krijgen tot gegevens van diverse aangesloten Data aanbieders, voornamelijk onderwijsinstellingen. In deze documentatie worden de stappen beschreven die nodig zijn om een verbinding tot stand te brengen en gegevens op te vragen.

Stap 1: Een account aanvragen

Om te beginnen moet je een account aanvragen om toegang te krijgen tot SURFeduhub. Volg deze stappen:

  1. Stuur een e-mail: Neem contact op met het SURFeduhub-managementteam via surfeduhub-beheer@surf.nl.
  2. Vermeld de vereiste informatie: Geef uw naam, organisatie, de persoonlijke e-mailadressen van de beoogde gebruikers van het SURFeduhub Dashboard en een korte beschrijving van het beoogde gebruik van de gegevens op.

Zodra uw aanvraag is goedgekeurd, worden er uitnodigingen via SURFconext verzonden. Door deze uitnodiging te accepteren, krijg je toegang tot het SURFeduhub Dashboard.

Stap 2: Registreer uw applicatie in het SURFeduhub Dashboard

Binnen het SURFeduhub Dashboard kunnen applicatiebeheerders hun applicatie registreren. Tijdens dit proces worden inloggegevens de afnemer verstrekt. Deze inloggegevens verlenen toegang tot de SURFeduhub Gateway.

Stap 3: SURFeduhub omgevingen

Er zijn twee SURFeduhub omgevingen:

  • Sandbox:
  • Live:
    • Doel: Voor productiegebruik, waarbij aangesloten aanbieders gegevens op productieniveau leveren.
    • Gateway-URL: gateway.surfeduhub.nl

Inloggegevens

  • Inloggegevens zijn geldig voor zowel de Sandbox- als de Live-omgeving. Inloggegevens worden verkregen via het SURFeduhub Dashboard op dashboard.surfeduhub.nl.

Stap 4: Een HTTP-verzoek indienen

Om gegevens op te halen, moet je een HTTP-verzoek indienen bij de SURFeduhub Gateway. Hieronder wordt beschreven hoe je dit doet:

Structuur van het HTTP-verzoek

  • Methode: Meestal GET voor het ophalen van gegevens.
  • URL: Het eindpunt dat door SURFeduhub wordt verstrekt voor de specifieke gegevensleverancier.

Authenticatie

Maak gebruik van Basic-authenticatie om verbinding te maken met de SURFeduhub Gateway. Vermeld uw inloggegevens in de verzoekheaders:

Authorization: Basic base64_encode(username:password)

Voorbeeld Request

Hier volgt een voorbeeld van hoe een HTTP-verzoek is op te bouwen:

GET /courses HTTP/1.1
Host: gateway.test.surfeduhub.nl  # For Sandbox
# or
Host: gateway.surfeduhub.nl        # For Live
Accept: application/json; version=5 # to make sure you get OOAPI v5 data
Authorization: Basic base64_encode(your_username:your_password)

Omgaan met samengevoegde gegevens

Als uw verzoek gegevens van meerdere aanbieders betreft, zal de SURFeduhub Gateway deze gegevens samenvoegen en in een envelopformaat verpakken. Het antwoord bevat metagegevens waarin de bron van elke dataset wordt aangegeven.

Standaard wordt uw verzoek doorgestuurd naar alle aanbieders die je toegang hebben verleend. Om aan te geven bij welke aanbieders je gegevens wilt opvragen, voeg je het volgende toe aan uw verzoek:

X-Route: endpoint=<comma-seperated list of endpoint ids>

Stap 5: Het antwoord verwerken

Het antwoord van de SURFeduhub Gateway wordt in JSON-formaat geleverd. Zorg ervoor dat je applicatie zo is ingesteld dat deze formaten correct kan parsen en verwerken.

Voorbeeld van de structuur van een antwoord

Een voorbeeld van een typisch JSON-antwoord zou er als volgt uit kunnen zien:

{
  "gateway": {
    "requestId": "6MQ7bfxpR3dXEBhn5383eL",
    "traceparent_trace_id": "61ae56f1460d50d4730b16534d309b4b",
    "traceparent_id": "1cf9ef2e4acff7a2",
    "request": "/",
    "endpoints": {
      "demo04.test.surfeduhub.nl": {
        "url": "https://demo04.test.surfeduhub.nl/",
        "responseCode": 200,
        "headers": {
          "content-length": "191",
          "content-type": "application/json"
        }
      },
      "demo06.test.surfeduhub.nl": {
        "url": "https://demo06.test.surfeduhub.nl/",
        "responseCode": 200,
        "headers": {
          "content-length": "191",
          "content-type": "application/json"
        }
      },
      "mimicry.test.surfeduhub.nl": {
        "url": "https://mimicry.test.surfeduhub.nl/eduxchange/",
        "responseCode": 200,
        "headers": {
          "content-length": "367",
          "content-type": "application/json"
        }
      },
      "demo05.test.surfeduhub.nl": {
        "url": "https://demo05.test.surfeduhub.nl/",
        "responseCode": 200,
        "headers": {
          "content-length": "191",
          "content-type": "application/json"
        }
      }
    }
  },
  "responses": {
    "demo04.test.surfeduhub.nl": {
      "contactEmail": "support@surfeduhub.nl",
      "documentation": "https://open-education-api.github.io/specification",
      "specification": "https://open-education-api.github.io/specification/v5/docs.html"
    },
    "demo06.test.surfeduhub.nl": {
      "contactEmail": "support@surfeduhub.nl",
      "documentation": "https://open-education-api.github.io/specification",
      "specification": "https://open-education-api.github.io/specification/v5/docs.html"
    },
    "mimicry.test.surfeduhub.nl": {
      "contactEmail": "admin@universiteitvanharderwijk.nl",
      "specification": "https://rawgit.com/open-education-api/specification/v3/docs.html#tag/course-offerings/paths/~1course-offerings/get",
      "documentation": "https://open-education-api.github.io/specification/v4/docs.html",
      "consumers": [
        {
          "consumerKey": "x-test-consumer",
          "additional": "custom",
          "attributes": "here"
        }
      ],
      "ext": {}
    },
    "demo05.test.surfeduhub.nl": {
      "contactEmail": "support@surfeduhub.nl",
      "documentation": "https://open-education-api.github.io/specification",
      "specification": "https://open-education-api.github.io/specification/v5/docs.html"
    }
  }
}

Problemen oplossen

  • Ongeldige inloggegevens: Zorg ervoor dat je de juiste gebruikersnaam en het juiste wachtwoord gebruikt. Controleer of er geen typefouten in staan.
  • Toegang geweigerd: Als je een melding krijgt dat de toegang is geweigerd, controleer dan of je over de benodigde rechten beschikt voor de gevraagde gegevensprovider.
  • Problemen met het antwoordformaat: Zorg ervoor dat uw applicatie het antwoordformaat (JSON) correct verwerkt.

Conclusie

Om als gegevensgebruiker verbinding te maken met SURFeduhub moet je een account aanvragen, de toegangsregels begrijpen, de weg vinden in de Sandbox- en Live-omgevingen, geauthenticeerde HTTP-verzoeken indienen en antwoorden effectief verwerken. Neem voor verdere hulp contact op met het SURFeduhub team via surfeduhub-beheer@surf.nl. 

Overview

SURFeduhub is a centralized platform that allows data consumers to access data from various connected data providers, primarily educational institutions. This documentation outlines the steps needed to establish a connection and request data.

Step 1: Request an Account

To begin, you must request an account to gain access to SURFeduhub. Follow these steps:

  1. Send an Email: Contact the SURFeduhub management team at surfeduhub-beheer@surf.nl.
  2. Include Required Information: Provide your name, organization, personal e-mail addresses of the intended SURFeduhub Dashboard users, and a brief description of your intended use of the data.

Once your request is approved, SURFconext invites will be sent. Accepting this invite will grant access to SURFeduhub Dashboard.

Step 2: Register your Application in SURFeduhub Dashboard

Within SURFeduhub Dashboard, Application Managers are able to register their Application. Client credentials are provided during this process. These credentials grants access to SURFeduhub Gateway.

Step 3: SURFeduhub Environments

There are two SURFeduhub environments:

  • Sandbox:

  • Live:

    • Purpose: For production use, where connected providers should provide production-level data.
    • Gateway URL: gateway.surfeduhub.nl

Credentials

  • Credentials are valid for either the Sandbox or Live environments. Credentials are obtained through SURFeduhub Dashboard. (dashboard.surfeduhub.nl)

Step 4: Making an HTTP Request

To retrieve data, you will need to perform an HTTP request to the SURFeduhub gateway. The following details outline how to do this:

HTTP Request Structure

  • Method: Typically GET for retrieving data.
  • URL: The endpoint provided by SURFeduhub for the specific data provider.

Authentication

You will use Basic Authentication to connect to the SURFeduhub gateway. Include your credentials in the request headers:

Authorization: Basic base64_encode(username:password)

Example Request

Here’s an example of how to structure your HTTP request:

GET /courses HTTP/1.1
Host: gateway.test.surfeduhub.nl  # For Sandbox
# or
Host: gateway.surfeduhub.nl        # For Live
Accept: application/json; version=5 # to make sure you get OOAPI v5 data
Authorization: Basic base64_encode(your_username:your_password)

Handling Aggregated Data

If your request involves data from multiple providers, the SURFeduhub gateway will aggregate this data and wrap it in an envelope format. The response will include metadata indicating the source of each dataset.

By default your request will be forwarded to all providers that have granted you access. To specify from which providers you would like to request, add the following to your request:

X-Route: endpoint=<comma-seperated list of endpoint ids>

Step 5: Processing the Response

The response from the SURFeduhub gateway will be in JSON format. Make sure your application is set up to parse and handle these formats appropriately.

Example Response Structure

An example of a typical JSON response might look like this:

{
  "gateway": {
    "requestId": "6MQ7bfxpR3dXEBhn5383eL",
    "traceparent_trace_id": "61ae56f1460d50d4730b16534d309b4b",
    "traceparent_id": "1cf9ef2e4acff7a2",
    "request": "/",
    "endpoints": {
      "demo04.test.surfeduhub.nl": {
        "url": "https://demo04.test.surfeduhub.nl/",
        "responseCode": 200,
        "headers": {
          "content-length": "191",
          "content-type": "application/json"
        }
      },
      "demo06.test.surfeduhub.nl": {
        "url": "https://demo06.test.surfeduhub.nl/",
        "responseCode": 200,
        "headers": {
          "content-length": "191",
          "content-type": "application/json"
        }
      },
      "mimicry.test.surfeduhub.nl": {
        "url": "https://mimicry.test.surfeduhub.nl/eduxchange/",
        "responseCode": 200,
        "headers": {
          "content-length": "367",
          "content-type": "application/json"
        }
      },
      "demo05.test.surfeduhub.nl": {
        "url": "https://demo05.test.surfeduhub.nl/",
        "responseCode": 200,
        "headers": {
          "content-length": "191",
          "content-type": "application/json"
        }
      }
    }
  },
  "responses": {
    "demo04.test.surfeduhub.nl": {
      "contactEmail": "support@surfeduhub.nl",
      "documentation": "https://open-education-api.github.io/specification",
      "specification": "https://open-education-api.github.io/specification/v5/docs.html"
    },
    "demo06.test.surfeduhub.nl": {
      "contactEmail": "support@surfeduhub.nl",
      "documentation": "https://open-education-api.github.io/specification",
      "specification": "https://open-education-api.github.io/specification/v5/docs.html"
    },
    "mimicry.test.surfeduhub.nl": {
      "contactEmail": "admin@universiteitvanharderwijk.nl",
      "specification": "https://rawgit.com/open-education-api/specification/v3/docs.html#tag/course-offerings/paths/~1course-offerings/get",
      "documentation": "https://open-education-api.github.io/specification/v4/docs.html",
      "consumers": [
        {
          "consumerKey": "x-test-consumer",
          "additional": "custom",
          "attributes": "here"
        }
      ],
      "ext": {}
    },
    "demo05.test.surfeduhub.nl": {
      "contactEmail": "support@surfeduhub.nl",
      "documentation": "https://open-education-api.github.io/specification",
      "specification": "https://open-education-api.github.io/specification/v5/docs.html"
    }
  }
}

Troubleshooting

  • Invalid Credentials: Ensure you are using the correct username and password. Check for any typos.
  • Access Denied: If you receive an access denied message, confirm that you have the necessary permissions for the requested data provider.
  • Response Format Issues: Ensure your application is correctly parsing the response format (JSON).

Conclusion

Connecting as a data consumer to SURFeduhub involves requesting an account, understanding access regulations, navigating the Sandbox and Live environments, making authenticated HTTP requests, and processing responses effectively. For further assistance, please reach out to the SURFeduhub support team at the email provided above.




  • No labels