Incoming Mobility ToRs CNR API

• What is the status of this document?
• See the index of all other EWP Specifications

Summary

This document describes the Incoming Mobility ToRs CNR API. This API is implemented by the sending institution if it wants to be notified whenever Transcript of Records served by the receiving institution (via the Incoming Mobility ToRs API) are changed.

CNR stands for Change Notification Receiver. For a detailed introduction on how CNR APIs work, please read this page.

Reminder on vocabulary

Keep in mind that definitions of "sending HEI" and "receiving HEI" come from the "mobility vocabulary", not the "HTTP vocabulary". In case of this particular API this means that:

• sending HEI == responding HEI == server (HEI which is sending the student == HEI which implements the API, receives the HTTP request with the notification, and responds to it),
• receiving HEI == requesting HEI == client == caller (HEI which is receiving the student == HEI which publishes ToRs, and sends the HTTP request with the CNR).

As long as we use these terms consistently, there shouldn't be much confusion though.

Request method

• Requests MUST be made with HTTP POST method. Servers MAY reject all other request methods.

Request parameters

Parameters MUST be provided in the application/x-www-form-urlencoded format.

receiving_hei_id (required)

Identifier of the receiving HEI - the master of the Transcript of Records which just have been changed.

omobility_id (repeatable, required)

A list of identifiers of Outgoing Mobility objects (no more than <max-omobility-ids> items). These are the Mobility objects for which Transcripts of Records have been recently updated (or created) on the caller's side.

This parameter is repeatable, so the request MAY contain multiple occurrences of it. The server SHOULD process all of them. Server implementers provide their own chosen value of <max-omobility-ids> via their manifest entry (see manifest-entry.xsd). Clients SHOULD parse this value (or assume it's equal to 1).

Security

This version of this API uses standard EWP Authentication and Security, Version 2. Server implementers choose which security methods they support by declaring them in their Manifest API entry.

This API does not expose any sensitive data, it only notifies the server that it should reload portions of its data. For this reason, it is RECOMMENDED for server implementers to not be overly strict on security methods they require (i.e. it is RECOMMENDED to not require extra layers of encryption in requests and responses - TLS seems more than enough).

Handling of invalid parameters

• General error handling rules apply.

• Servers MUST return a valid (HTTP 200) XML response whenever the request has been properly received. Unless HTTP 200 is received, clients are RECOMMENDED to automatically retry the request after some time.

Response

Servers MUST respond with a valid XML document described by the response.xsd schema. See the schema annotations for further information.

Safety measures

It is NOT guaranteed that all notifications will be delivered to you promptly. Some notifications may also not reach you at all, e.g. due to implementation errors on the caller's server, or the fact that no Notification Sender daemon has been implemented there (see <sends-notifications> element in Incoming Mobility ToRs API's manifest-entry.xsd).

Therefore, you SHOULD periodically verify if your copies are up-to-date (or, simply, choose to not store these copies). Proper caching techniques and/or periodical use of index endpoint of Incoming Mobility ToRs API can help you with that.