Documentation for data consumers

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:

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

Once your request is approved, you will receive a set of credentials (username and password) that will allow you to access data from authorized providers.

Step 2: Understand Access Regulations

Your access is limited to specific data providers that have granted you permission. This access is managed at the API path level, meaning that you will only be able to request data from endpoints and paths you are authorized to access.

Note: Data consumers should directly contact data providers to request access to their data. The providers will subsequently reach out to SURF to make the necessary changes for your access.

Step 3: SURFeduhub Environments

There are two SURFeduhub environments:

Sandbox:
- Purpose: For testing purposes.
- Gateway URL: gateway.test.surfeduhub.nl
- Demo Providers: The Sandbox environment includes demo providers, and SURF can connect your account to these providers for testing.
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. If you need access to both environments, you will receive two separate sets of credentials.

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.

Page tree