ALMA API Documentation

Ontology

The ALMA Ontology comprises concepts organized in several concept schemes, according to the Simple Knowledge Organization System (SKOS) W3C recommendation. Each element, both concepts and concept schemes, are represented by a URI (Uniform Resource Identifier), which follow the format <namespace>:<elementName>. In addition, a label provides a human-readable name. Relations between concepts, even across schemes, can be either asymmetrical (inheritance, broader topic) or symmetrical (synonyms, related topics).

API

The base URL for the ALMA API is https://alma.uni.lu/api/

Retrieval of Concepts & Concept Schemes

• schemes/

  Returns a JSON array of objects representing a scheme, containing its uri, title and id.

  For example:

    [
      {
        "id": 1,
        "uri": "programming:Scheme",
        "title": "Programming"
      },
      ...
    ]
  

• schemes/<namespace>:Scheme/, schemes/<namespace>/

  Returns a JSON array of objects representing a concept in the scheme indicated by the scheme's namespace. The objects comprise the uri and label of a concept.

  For example, when retrieving the concepts in the scheme java:Scheme:

    [
      {
        "uri": "java:ForLoop",
        "label": "For-Loop"
      },
      ...
    ]
  

  If no scheme could be found for the indicated namespace, the JSON null value is returned.

  For the sake of convenience, there are 3 dedicated endpoints for the concepts from the meta-scheme curriculum:Scheme

  • institutions/ Institutions, e.g. Université du Luxembourg
  • courses/ Course, e.g. Programming 1
  • terms/ Terms, e.g. WS 2017/2018

  
  

  Also, the optional GET parameter excludeNoLabel allows to filter out any concepts with no explicit human-readable label, e.g. for java:Scheme.

• concepts/<uri>/

  Returns, for the concept indicated by its uri, a JSON object including its label, the broader/parent concepts, the scheme title, and the related concepts, as well as an id. If the given uri could not be found, an HTTP Error 400 (Bad Request) is returned.

  For example, when retrieving the concept java:ForLoop:

    {
      "uri": "java:ForLoop",
      "label": "For-Loop",
      "broader": [],
      "scheme": "Java",
      "related": ["programming:ForLoop"],
      "parent": ["java:Statement"],
      "id": 430
    }
  

• concepts/<uri>/label/

  For performance reasons, there is also a dedicated endpoint for only retrieving the label of a concept identified by its uri, returned as a JSON string. If the given uri could not be found, an HTTP Error 400 (Bad Request) is returned.

  For example, concepts/java:ForLoop/label/ returns "For-Loop".

• ontology/

  Returns, in JSON format, the content of the whole ontology, i.e. an array of schemes containing their concepts. The concepts are described extensively, i.e. including their relationships to other concepts, as described above.

Retrieval of Learning Material

• concepts/<uri>/resources/

  Returns a JSON array of objects representing learning resources indexed for the concept of the given uri. If an invalid uri is provided, an HTTP Error 400 (Bad Request) is returned. If the uri could not be found, or no documents are indexed for the given uri, an empty JSON array [] is returned. Each object representing a learning resource comprises the id of the resource, the type of learning resource (e.g. PDF) and the url to the resource.

  For example, concepts/java:If/resources/ returns the list of learning resources index for the java:If concept:

    [
      {
        "id": 42,
        "type": "pdf",
        "url": "https://alma.uni.lu/media/f9362a4f6b334cdf8d0be3ab7c8547b1.pdf#page=1"
      },
      ...
    ]
  

  If the GET parameter extended is specified, and no resources are found for the specified concept, the search goes on until

  • any resources are found, or
  • no related concepts are found anymore (breadth-first search)

  This parameter makes also sure that the title and previewURL are included in the resource details. This is a convenience measure to avoid a subsequent call to the resources/<id>/ endpoint (see below).

• resources/<id>/

  Returns a JSON object of the learning resource identified by the provided id, or an HTTP Error 404 if non-existent. This object comprises:

  • id: The ID of the resource.
  • documentUUID: A document UUID for regrouping resources of a same document (e.g. pages in PDF, Idea Spaces in Curio).
  • type: The type of learning resource (current values: word, ppt, pdf, so, curio, video, web, yactul, ar)
  • indexer: Information about the user who indexed the resource.
  • url: The URL to the resource.
  • date: The UNIX timestamp of the indexing.
  • title: The title of the resource.
  • concepts: An array of JSON objects comprising the uri and label of the concepts annotated on this resource.
  • previewURL: The URL of the preview image (or null if non-existent).

  For example:

    {
      "id": 734,
      "documentUUID": "28c5e942-b1d0-47ea-bccc-6022f20e4615",
      "type": "curio",
      "indexer": {
          "id": 1,
          "firstname": "Christian",
          "username": "christian",
          "surname": "Gr\u00e9visse"
      },
      "url": "https://coast.uni.lu/teaching/programming2/scrapbook/#40",
      "date": 1523286400,
      "title": "Array of Pointers to Struct",
      "concepts": [
          {
              "uri": "c:ArrayType",
              "label": "Array Type"
          }, {
              "uri": "c:Pointer",
              "label": "Pointer"
          }, {
              "uri": "c:Struct",
              "label": "Struct"
          }, {
              "uri": "c:StructDeclaration",
              "label": "Struct Declaration"
          },
          ...
      ],
      "previewURL": "https://alma.uni.lu/media/resourceThumbs/83427808-3c34-11e8-a604-0050569a2b96.png"
    }
  

• resources/<type>/

  Returns a JSON object containing a resources array comprising all resource IDs of the given type. These IDs can be used together with the resources/<id>/ endpoint (see above). An HTTP Error 400 is returned if the provided type is not among word, ppt, pdf, so, curio, video, web, yactul or ar.

• learningmaterial/

  This endpoint expects a POST request with a JSON body comprising the arrays concepts (i.e. the concepts learning resources shall be searched for) and, optionally, extraFilters (i.e. filters like the institution, course or term). Both arrays shall contain concept URIs.

  In addition, session- and context-based retrieval of learning material can be achieved by adding the following (optional) parameters:

  • session: A session UUID (to distinguish between different contexts)
  • app: The name of the app (e.g. Eclipse)
  • context: The "name" of the context (e.g. the name of the project, of the lab sheet)
  • file: The name of the file (e.g. main.c)
  • selection: A base64-encoding of some selection (e.g. the selected code snippet). If the provided data is not a valid base64 encoding, the verbatim value is used.

  For example, if learning material for the concepts java:If and java:WhileLoop shall be retrieved within the course:programming1 at the institution:unilu, the request would be:

    {
      "concepts": [
        "java:If",
        "java:WhileLoop"
      ],
      "extraFilters": [
        "institution:unilu",
        "course:programming1"
      ],
      "app": "Eclipse",
      "file": "Sum.java",
      "context": "Lab 3",
      "session": "42a75659-86e0-4e5c-a907-d01660225c9c",
      "selection": "aWYgKG4gPT0gMCkgewp9CiBlbHNlIHsKfQ=="
    }
  

  and returns a JSON array of objects comprising the description of a concept (uri and label) as well as a list of related resources. Latter are described by a title, a url to the resource itself and a previewURL to a preview image (if any, otherwise null). In addition, the field visitID can be used for visiting (visit/) and rating (rate/) a resource (see below).

  For example, the above request would result in the following:

    [
      {
        "concept": {
          "uri": "java:If",
          "label": "If-Condition"
        },
        "resources": [
          {
            "previewURL": "http://alma.uni.lu/media/resourceThumbs/8e319aba-af20-11e7-86c0-0050569a2b96.png",
            "title": "prog1_if-condition1",
            "url": "https://alma.uni.lu/media/f9362a4f6b334cdf8d0be3ab7c8547b1.pdf#page=1",
            "visitID": 185
          },
          ...
        ]
      },
      ...
    ]
  

  This endpoint returns either a HTML-rendered page or the data in JSON format. To enforce a JSON response, the HTTP Accept header has to be set to application/json. If the ALMA server is set to exam mode, this endpoint, used by the ALMA 4 Eclipse plugin, will return the following error status:

    { 'error': 'Exam Mode is active!' }
  

• visit/

  This endpoint expects a POST request with a parameter id (the ID of a resource visit, which is returned by the learningmaterial/ call). The value true is returned. If an invalid ID is provided, an HTTP error 404 is raised.

• likert/

  This endpoint returns a JSON array of objects representing a Likert item, containing its id and question.

  For example:

    [
      {
          "id": 1,
          "question": "Type/Format"
      },
      {
          "id": 2,
          "question": "Content"
      },
      {
          "id": 3,
          "question": "Language"
      }
    ]
  

• rate/

  This endpoint expects a POST request with the parameters resourceVisitID (which is returned by the learningmaterial/ call), likertItemID (which can be retrieved by the likert/ call) and an integer value. A rating for a given resource visit and Likert item can be given several times, updating the previous value (if any). If the resource visit or Likert item is not found, an HTTP error 404 is raised. Otherwise, a boolean value stating whether the rating is new (true) or updated (false) is returned.

• suggest/

  This endpoint expects a POST request with the parameters url, tags (an array of concept URIs) and visit (which is returned by the learningmaterial/ call). If a resource with this URL does not yet exist on the repository, it will be added, yet it will not be retrievable from the , e.g., learningmaterial/ call as long as it has not been activated by an admin.

    {
        url: "http://...",
        tags: ["c:printf", "c:String"],
        visit: 42
    }
  

• trending/

  This endpoint returns a JSON array of objects comprising the description of a concept (uri and label) as well as the count of concept visits (see learningmaterial/) within the last hour.

Reference

When using the ALMA ontology in your research, please cite the following publication:

@InProceedings{Grevisse2017,
  author="Gr{\'e}visse, Christian and Botev, Jean and Rothkugel, Steffen",
  editor="Solano, Andr{\'e}s and Ordo{\~{n}}ez, Hugo",
  title="An Extensible and Lightweight Modular Ontology for Programming Education",
  booktitle="Advances in Computing",
  year="2017",
  publisher="Springer International Publishing",
  address="Cham",
  pages="358--371",
  isbn="978-3-319-66562-7"
}