API Documentation

This document contains the X5GON platform REST API documentation. It contains all of the API routes and their explanation; the route, the possible parameters, and the response. The document is split into sections based on the functionality of the API routes.

Connect Service

The library that enables connection between the OER repository and the X5GON platform. The full documentation of the library is available HERE.

https://platform.x5gon.org/api/v1/snippet/{version}/x5gon-log.min.js

Library URL parameters
version Type: String Title: Library Version Optional: false The version of the library. The options are: v1, v2, and latest. If latest, it will automatically take the latest version available.

To include the library add the following line in the repository site header. Replace the latest parameter with the appropriate library URL parameter value.

<script
     type="text/javascript"
     src="https://platform.x5gon.org/api/v1/snippet/latest/x5gon-log.min.js"
></script>

Connect Recommender

Enables embedding of recommendations into HTML. The request URL is different, as shown below.

https://platform.x5gon.org/embed/recommendations?text=text&url=url&width=width&height=height

Query string parameters
text Type: String Title: Query Text Optional: true The query text. Longer text provides better results. If both text and url query parameters are present, url has the priority.
url Type: String Title: Query URL Optional: true The query URL. The URL must be associated with a material stored in the X5GON database. If no such URL is found, it uses the text query parameter, if present.
width Type: String Title: Container Width Optional: true The embedded containers width. Used to setup the container into HTML. Default value is 280px.
height Type: String Title: Container Height Optional: true The embedded containers maximum height. Used to setup the container into HTML. Default value is 400px.
Embedding example

The recommendation results can be embedded by using different tags. The example shows how to embed the recommendation results using the iframe tag. We only use the text query parameter for the recommendations, and both width and height parameters to assign the size of the embedded page.
NOTE: the difference between the height query parameter and the iframes height style, which is 25px. This is due to the iframes default configuration.

<iframe
     src="https://platform.x5gon.org/embed/recommendations?text=machine%20learning&width=100%25&height=400px"
     style="border:0px;width:100%;height:425px"
></iframe>

The representation of the embedded recommendations.

REST API

All URLs referenced in the REST API section have the following base:

https://platform.x5gon.org/api/v1

The X5GON Platform REST API is served over HTTPS.

Recommender REST API

The Recommender REST API allows the user to retrieve OER materials that are similar to the given query.

Available methods
GET /search Get a list of relevant open educational resources
GET /recommend/oer_materials Get a list of relevant open educational resources
GET /recommend/oer_bundles Get a list of most relevant open educational bundles
GET /recommend/collaborative_filtering Get a list of personalized open educational bundles
Search for relevant materials
GET /search

Get a list of relevant open educational resources (10 per page).

Query string parameters
text Type: String Title: Query Text Optional: false The seed text from which the system finds the relevant open educational resources.
type Type: String Title: Material Type Optional: true The type of open educational resources. Possible options: all, video, audio and text. Default value is all.
page Type: Integer Title: Page Optional: true The page number of the recommended list. Default value is 1.
Response body attributes
query Type: JSON Title: Query Parameters Read only: true A JSON object containing the provided query parameters.
query object properties
text Type: String Title: Query Text Read only: true The user provided query text.
type Type: String Title: Material Type Read only: true The material type provided.
page Type: Integer Title: Result Page Read only: true The page number of the results.
rec_materials Type: Array Title: Recommended Materials Read only: true An array of objects, each representing an recommended open educational resource.
rec_materials object properties
material_id Type: Integer Title: Material ID Read only: true The unique ID of the OER material.
weight Type: Float Title: Recommendation Weight Read only: true The number between 0 and 1 representing the relevance of the OER material. Greater weight means bigger relevance.
url Type: String Title: Material URL Read only: true The URL of the OER material.
title Type: String Title: Material Title Read only: true The title of the OER material.
description Type: String Title: Material Description Read only: true The description of the OER material.
provider Type: String Title: Material Provider Read only: true The name of the OER materials provider.
language Type: String Title: Material Language Read only: true The language of the OER material in ISO 639-1 code.
wikipedia Type: Array Title: Material Wikipedia Concepts Read only: true An array of objects, each representing the most relevant wikipedia concept of the material.
wikipedia object properties
concept Type: String Title: Wikipedia Concept Read only: true The Wikipedia concept represented as an URL.
support Type: Integer Title: Wikipedia Concept Support Read only: true The amount of elements in the material that support the given Wikipedia concept.
type Type: String Title: Material Type Read only: true The type of the OER material.
metadata Type: JSON Title: Result Metadata Read only: true A JSON object containing the associated metadata. Helpful for navigating through the recommendations.
metadata object properties
num_or_materials Type: Integer Title: Number of Found Materials Read only: true Number of most relevant relevant recommendations.
max_pages Type: Integer Title: Max Pages Read only: true The total number of result pages.
Get a list of most relevant open educational resources (similar to /search)
GET /recommend/oer_materials

Get a list of most relevant open educational resources.

Query string parameters
text Type: String Title: Query Text Optional: false The seed text from which the system finds the relevant open educational resources.
type Type: String Title: Material Type Optional: true The type of open educational resources. Possible options: all, video, audio and text. Default value is all.
page Type: Integer Title: Page Optional: true The page number of the recommended list. Default value is 1.
Response body attributes
rec_materials Type: Array Title: Recommended Materials Read only: true An array of objects, each representing an recommended open educational resource.
rec_materials object properties
material_id Type: Integer Title: Material ID Read only: true The unique ID of the OER material.
weight Type: Float Title: Recommendation Weight Read only: true The number between 0 and 1 representing the relevance of the OER material. Greater weight means bigger relevance.
url Type: String Title: Material URL Read only: true The URL of the OER material.
title Type: String Title: Material Title Read only: true The title of the OER material.
description Type: String Title: Material Description Read only: true The description of the OER material.
provider Type: String Title: Material Provider Read only: true The name of the OER materials provider.
language Type: String Title: Material Language Read only: true The language of the OER material in ISO 639-1 code.
wikipedia Type: Array Title: Material Wikipedia Concepts Read only: true An array of objects, each representing the most relevant wikipedia concept of the material.
wikipedia object properties
concept Type: String Title: Wikipedia Concept Read only: true The Wikipedia concept represented as an URL.
support Type: Integer Title: Wikipedia Concept Support Read only: true The amount of elements in the material that support the given Wikipedia concept.
type Type: String Title: Material Type Read only: true The type of the OER material.
Get a list of relevant open educational bundles (web pages)
GET /recommend/oer_bundles

Get a list of relevant open educational bundles (web pages).

Query string parameters
url Type: String Title: website URL Optional: false The URL of the website containing the OER materials. The URL must be present in the X5GON database
page Type: Integer Title: Page Optional: true The page number of the recommended list. Default value is 1.
Response body attributes
rec_bundles Type: Array Title: Recommended Bundles Read only: true An array of objects, each representing an recommended open educational resource bundle.
rec_bundles object properties
weight Type: Float Title: Recommendation Weight Read only: true The number of common concepts between the given url bundle and this OER bundle. Greater weight means bigger relevance.
url Type: String Title: Bundle URL Read only: true The URL of the OER bundle.
title Type: String Title: Bundle Title Read only: true The title of the OER bundle.
description Type: String Title: Bundle Description Read only: true The description of the OER bundle.
provider Type: String Title: Bundle Provider Read only: true The name of the OER bundle provider.
language Type: String Title: Bundle Language Read only: true The dominant language of the OER bundle in ISO 639-1 code.
wikipedia Type: Array Title: Bundle Wikipedia Concepts Read only: true An array of objects, each representing the most relevant wikipedia concept of the bundle.
wikipedia object properties
concept Type: String Title: Wikipedia Concept Read only: true The Wikipedia concept represented as an URL.
support Type: Integer Title: Wikipedia Concept Support Read only: true The amount of elements in the material that support the given Wikipedia concept.
type Type: String Title: Bundle Type Read only: true The dominant type of the OER bundle.
Get a list of personalized open educational bundles recommendations
GET /recommend/collaborative_filtering

Get a list of personalized open educational bundles recommendations. The personalization is performed via the collaborative filtering method.

Query string parameters
page Type: Integer Title: Page Optional: true The page number of the recommended list. Default value is 1.
Response body attributes
rec_bundles Type: Array Title: Personalized Bundles Read only: true An array of objects, each representing an recommended open educational resource bundle.
rec_bundles object properties
weight Type: Float Title: Recommendation Weight Read only: true The number of times the bundle was viewed by similar users. Greater weight means bigger relevance.
url Type: String Title: Bundle URL Read only: true The URL of the OER bundle.
title Type: String Title: Bundle Title Read only: true The title of the OER bundle.
description Type: String Title: Bundle Description Read only: true The description of the OER bundle.
provider Type: String Title: Bundle Provider Read only: true The name of the OER bundle provider.
language Type: String Title: Bundle Language Read only: true The dominant language of the OER bundle in ISO 639-1 code.
wikipedia Type: Array Title: Bundle Wikipedia Concepts Read only: true An array of objects, each representing the most relevant wikipedia concept of the bundle.
wikipedia object properties
concept Type: String Title: Wikipedia Concept Read only: true The Wikipedia concept represented as an URL.
support Type: Integer Title: Wikipedia Concept Support Read only: true The amount of elements in the material that support the given Wikipedia concept.
type Type: String Title: Bundle Type Read only: true The dominant type of the OER bundle.

Query REST API

This section contains the API routes for retrieving resources based on the query parameters. It contains different examples of resource retrieval based on the provided query parameters. NOTE: Some of the API routes are private and are available only to those who have special credentials.

Query REST API: Open Educational Resources

The Open Educational Resources REST API allows the user to retrieve OER materials.

Available methods
GET /oer_materials Get a list of open educational resources
POST /oer_materials Upload a list of open educational resources
GET /oer_materials/{material_id} Get information of a specific open educational resource
GET /oer_materials/{material_id}/contents Get a list of content of a specific open educational resource
GET /oer_materials/{material_id}/contents/{content_id} Get information of a specific content of a specific open educational resource
GET /oer_materials/{material_id}/contents/{content_id}/value Get the body value of a specific content of a specific open educational resource
Get a list of open educational resources
GET /oer_materials

Get a list of open educational resources.

Query string parameters
languages Type: Array Title: Languages Optional: true A comma-separated list of languages in ISO 639-1 code.
limit Type: Integer Title: Limit Optional: true The number of records to return. Default value is 20.
offset Type: Integer Title: Offset Optional: true The number of records from a collection to skip. Iterating over large collections with this parameter can be slow. Default value is 0.
page Type: Integer Title: Page Optional: true The page number of the record collection. It overrides the offset parameter.
Response body attributes
oer_materials Type: Array Title: OER Materials Read only: true An array of objects, each representing an open educational resource.
oer_materials object properties
material_id Type: Integer Title: Material ID Read only: true The unique ID of the OER material.
title Type: String Title: Material Title Read only: true The title of the OER material.
description Type: String Title: Material Description Read only: true The description of the OER material.
url Type: String Title: Material URL Read only: true The URL of the OER material.
language Type: String Title: Material Language Read only: true The language of the OER material in ISO 639-1 code.
type Type: String Title: Material Type Read only: true The type of the OER material.
mimetype Type: String Title: Material Mimetype Read only: true The mimetype of the OER material.
content_ids Type: Array Title: Material Content IDs Read only: true The IDs of the material contents. Can be accessed through content info method.
provider Type: JSON Title: Material Provider Read only: true The JSON object containing the provider's name and domain.
Upload a list of open educational resources
POST /oer_materials

Uploads a list of open educational resources.

Request body parameters
api_key Type: String Title: API Key Optional: false The API key used to submit the OER materials. NOTE: to obtain an API key, please contact the project administrator.
oer_materials Type: Array Title: OER Materials Optional: false An array of objects, each representing an open educational resource.
oer_materials object properties
title Type: String Title: Material Title Optional: false The title of the OER material.
description Type: String Title: Material Description Optional: true The description of the OER material.
provider_uri Type: String Title: Provider URI Optional: false The URL of the webpage on which the material is located.
material_url Type: String Title: Material URL Optional: false The URL of the OER material.
language Type: String Title: Material Language Optional: false The language of the OER material in ISO 639-1 code.
type Type: String Title: Material Type Optional: false An object containing the type information of an open educational resource.
type object properties
ext Type: String Title: Material Extension Optional: false The extension of the material (i.e. .pdf, .mov, etc).
mime Type: String Title: Material Mimetype Optional: false The mimetype of the material.
date_created Type: Datetime Title: Material Creation Date Optional: true The date of the materials creation. Format is YYYY-MM-DD.
provider_token Type: String Title: Material Provider Token Optional: false The token of the material provider. Token must be first created via the registration form.
license Type: String Title: Material License Optional: false The material license. Since we are dealing with OER materials, the license should be CC-BY.
Response body attributes
num_submitted Type: Integer Title: Number of Materials Submitted Read only: true Number of successfully submitted materials.
errors Type: Object Title: Submission Errors Read only: true The object containing submission error information. NOTE: only present if there are any errors.
errors object properties
message Type: String Title: Error Message Read only: true The submission error message.
invalid_count Type: Integer Title: Invalid Count Read only: true Number of invalid materials.
invalid_materials Type: Array Title: Invalid Materials Read only: true An array of not valid material objects format.
invalid_materials object properties
material Type: Object Title: OER Material Read only: true The OER material object with a not valid format.
errors Type: Array Title: Material Errors Read only: true An array of errors telling why is the material object not valid.
Get information of a specific open educational resource
GET /oer_materials/{material_id}

Get information of a specific open educational resource.

Path parameters
material_id The unique ID of the open educational resource.
Response body attributes
material_id Type: Integer Title: Material ID Read only: true The unique ID of the OER material.
title Type: String Title: Material Title Read only: true The title of the OER material.
description Type: String Title: Material Description Read only: true The description of the OER material.
url Type: String Title: Material URL Read only: true The URL of the OER material.
language Type: String Title: Material Language Read only: true The language of the OER material in ISO 639-1 code.
type Type: String Title: Material Type Read only: true The type of the OER material.
mimetype Type: String Title: Material Mimetype Read only: true The mimetype of the OER material.
content_ids Type: Array Title: Material Content IDs Read only: true The IDs of the material contents. Can be accessed through content info method.
provider Type: JSON Title: Material Provider Read only: true get-list-of-oer-contents The JSON object containing the provider's name and domain.
Get a list of content of a specific open educational resource
GET /oer_materials/{material_id}/contents

Get a list of content of a specific open educational resource.

Path parameters
material_id The unique ID of the open educational resource.
Response body attributes
oer_materials Type: JSON Title: OER Materials Read only: true The JSON object of the OER material with ID equal to material_id (path parameter).
oer_materials object properties
material_id Type: Integer Title: Material ID Read only: true The unique ID of the OER material.
oer_contents Type: Array Title: OER Material Contents Read only: true An array of objects, each representing a content of the open educational resource.
oer_contents object properties
content_id Type: Integer Title: Content ID Read only: true The unique ID of the content of OER material.
type Type: String Title: Content Type Read only: true The type of content. Possible types: text_extraction, transcription, or translation.
extension Type: String Title: Content Extension Read only: true The extension of content. Possible types: plain, or dfxp.
value Type: JSON Title: Content Value Read only: true The value of the content. Dependant of the content type and extension.
language Type: String Title: Content Language Read only: true The language of the OER material in ISO 639-1 code.
Get information of a specific content of a specific open educational resource
GET /oer_materials/{material_id}/contents/{content_id}

Get information of a specific content of a specific open educational resource.

Path parameters
material_id The unique ID of the open educational resource.
content_id The unique ID of the OER content.
Response body attributes
content_id Type: Integer Title: Content ID Read only: true The unique ID of the content of OER material.
type Type: String Title: Content Type Read only: true The type of content. Possible types: text_extraction, transcription, or translation.
extension Type: String Title: Content Extension Read only: true The extension of content. Possible types: plain, or dfxp.
value Type: JSON Title: Content Value Read only: true The value of the content. Dependant of the content type and extension.
language Type: String Title: Content Language Read only: true The language of the OER material in ISO 639-1 code.
Get the body value of a specific content of a specific open educational resource
GET /oer_materials/{material_id}/contents/{content_id}/value

Get the body value of a specific content of a specific open educational resource.

Path parameters
material_id The unique ID of the open educational resource.
content_id The unique ID of the OER content.
Response value
content body Type: String The body value of the content of a specific open educational resource.