Introduce "unbounded" ToRs

[wrygiel]

Not sure if "unbounded" is the best word to describe them, but it should do as a code name. What we mean here are ToRs which are not related to a mobility, and - as such - cannot be identified by omobility_id (the way they are currently identified in Incoming Mobility ToRs API).

Why would we want to support them? Some examples:

• Sharing without understanding mobilities: Perhaps some partners don't want to understand nominations and mobilities, but they still want to be able to share ToRs with other partners. (Currently, they are required to implement a client for Outgoing Mobilities API, and bind omobility_ids to their ToRs.)

• Sharing to a partner who doesn't (yet) understand mobilities: Perhaps we want to send a ToR to a partner which didn't implement Outgoing Mobilities API so far. (Currently we can't do that, because we need omobility_id to share, and this ID needs to be assigned by the partner. So we need to wait for the partner to implement Outgoing Mobilities API first.)

• Pushing partial ToRs at other partners: Perhaps it might be useful to allow the partner to share different subsections of the student's ToR with various receivers. (Currently each omobility_id identifies a unique ToR contents. There is no way to send different sections of student's achievements to other partners - there's only the option to send all achievements releated to that single mobility.)

Let's discuss possible solutions here. @erasmus-without-paper/all-members (I won't have time to specify those before I leave the project, but I will leave some of my thoughts behind.)

Solution 1 (two standalone APIs for ToR retrieval)

Leave Incoming Mobility ToRs unchanged, add separate Unbounded ToRs.

• Incoming Mobility ToRs API
  • get(receiving_hei_id, omobility_ids)
  • index(receiving_hei_id, sending_hei_ids, modified_since) - returns omobility_ids
• Incoming Mobility ToR CNR API
  • receive(receiving_hei_id, omobility_ids)
• Unbounded ToRs API
  • get(publisher_hei_id, tor_ids)
  • index(publisher_hei_id, reader_hei_id, modified_since) - returns tor_ids
• Unbounded ToR CNR API
  • receive(publisher_hei_id, tor_ids)

Pros:

• Partners which don't want to support unbounded ToRs, don't need to.

Cons:

• Separate, yet a bit coupled. Both get endpoints in two separate repos might need to be updated in unison.
• One ToR can be accessed in multiple ways. Might be confusing.

Solution 2 (split into Incoming Mobilities API and ToRs API)

Remove Incoming Mobility ToRs APIs. Replace them with ToRs API, when ToRs are identified by tor_id. Include these tor_ids in the existing Incoming Mobilities API.

• Incoming Mobilities API
  • get(receiving_hei_id, omobility_ids) - optional tor_id for each mobility
  • index(receiving_hei_id, sending_hei_ids, modified_since) - returns omobility_ids
• Incoming Mobility CNR API
  • receive(receiving_hei_id, omobility_ids) - will get called when ToRs get assigned to mobilities
• ToRs API
  • get(publisher_hei_id, tor_ids)
  • index(publisher_hei_id, reader_hei_id, modified_since) - returnstor_ids`
• ToR CNR API
  • receive(publisher_hei_id, tor_ids)

Pros:

• Fits the domain model.
• Concise, a bit more clear. Only one way to access a single ToR.

Cons:

• Partners will need to rewrite their ToR implementations.

Solution 3 (two get endpoints)

Pack both of these functionalities in a single API. Require partners to support two kinds of ToR identifiers (tor_ids and omobility_ids) in two separate endpoints. Both responses will use the same XML namespace, but will be served at different endpoints.

• ToRs API
  • get-for-mobility(receiving_hei_id, omobility_ids)
  • get(publisher_hei_id, tor_ids)
  • index(publisher_hei_id, reader_hei_id, modified_since) - returnstor_ids+ optionalomobility_id` for each
• ToR CNR API
  • get(tor_ids + optional omobility_id for each)

Cons:

• Partners will need to rewrite their ToR implementations.
• One ToR can be accessed in multiple ways. Might be confusing.

Solution 4 (one get endpoint with complex parameters)

Same as Solution 3, but merge the two endpoints into one. Use different ToR identifiers depending on the parameters passed.

• ToRs API
  • get(receiving_hei_id, omobility_ids)
  • get(publisher_hei_id, tor_ids)
  • index(publisher_hei_id, reader_hei_id, modified_since) - returnstor_ids+ optionalomobility_id` for each
• ToR CNR API
  • get(tor_ids + optional omobility_id for each)

Cons:

• Single get endpoint, but a bit complex parameter rules.
• Partners will need to rewrite their ToR implementations.
• One ToR can be accessed in multiple ways. Might be confusing.

Solution 5 (no omobility_ids in params)

Support only tor_ids. Don't allow to fetch ToRs by omobility_ids.

• ToRs API
  • get(publisher_hei_id, tor_ids) -> XML (with optional mobility IDs)
  • index(publisher_hei_id, reader_hei_id, modified_since) - returnstor_ids` only
• ToR CNR API
  • receive(publisher_hei_id, tor_ids)

Pros:

• Only one way to access a single ToR.

Cons:

• Client needs to fetch all ToRs before it's able to connect them to existing mobilities.
• Partners will need to rewrite their ToR implementations.
• Seems to be "wrong way around".

Solution 6 (broader "XML document" support)

• Transcript of Records Data Type (not an API)
  • defines the XML wrapper with: ELMO, tor_id, optional omobility_id.
• Documents API
  • get(publisher_hei_id, document_ids) - returns XML wrapper with a set of document_ids paired with xs:any elements
  • index(publisher_hei_id, document_types, reader_hei_ids, modified_since) - returns document_ids with document_type for each
  • document_id MAY contain a document_type prefix for better lookup performance (individual partner's choice)
  • document_type could be simply a namespace+elementname combined in a single string "{NS}name".
• Document CNR API
  • receive(document_ids + document_type for each)

Pros:

• Gives us room for future support for publishing other types of XML documents.

Cons:

• Client needs to fetch all ToRs before it's able to connect them to existing mobilities.
• Probably unnecessary (will be need to exchange any type of document?).

Solution 7 (broader "binary document" support)

• Transcript of Records Data Type (not an API)
  • defines the XML wrapper with: ELMO, tor_id, optional omobility_id.
• Documents API
  • get(publisher_hei_id, document_id) - returns raw content, with headers for document_type and content_type
  • index(publisher_hei_id, document_types, reader_hei_ids, modified_since) -> returns document_ids with document type, content type, and multilingual title for each
  • document_id MAY contain a document_type prefix for better lookup performance (individual partner's choice)
  • document_type would be an enumeration (but might also allow any string)
  • content_type is regular HTTP Content-Type string
• Document CNR API
  • receive(document_ids + document_type, content_type, and multilingual title for each)

Pros:

• Gives us room for future support for publishing any type of documents (XML, Word, PDF).

Cons:

• Heavier index and CNRs.
• Client needs to fetch all ToRs before it's able to connect them to existing mobilities.
• Probably unnecessary.

[wrygiel]

My personal opinion on these solutions:

• Solution 2 is my favourite one.
• Solutions 1, 3 and 4 are acceptable, but not as good.
• Solution 5 is bad. I think we still need to be able to easily fetch ToRs by their omobility_id.
• Solutions 6 and 7 seem completely unnecessary. We don't (yet) have any use cases for that.

[wrygiel]

We briefly talked about these solutions in our team. It seems that ideas proposed in solutions 6 and 7 are not as unnecessary as I believed. There seems to be a need for a "shared space" for exchanging documents between HEIs. ToRs are only one kind of such document (and one we'd like to focus on in the beginning).

After an hour of talk we came up with another solution which seems plausible.

Solution 8

We leave existing mobility-related ToR APIs "as they are". However, we also introduce an alternative way of exchanging any kind of documents (including unbounded ToRs).

• Documents API
  • get(publisher_hei_id, document_id) - returns raw content + metadata in headers
  • index(publisher_hei_id, document_types, reader_hei_ids, modified_since) -> returns document_ids along with their metadata
• Document CNR API
  • receive(document_ids) (not sure if metadata should be included in the request or not)

Metadata:

• Content-Type - regular HTTP Content-Type value
• Last-Modified - also per HTTP specs
• Ewp-Document-Type - this would be an enumeration, but might also allow any string
• Ewp-Document-Title - title, preferrably in English (do we need more languages?)

Pros:

• Compatible with existing approach (existing APIs stay as they are).
• Gives us room for future support for publishing any type of documents (XML, Word, PDF).

Cons:

• Heavier index (lots of metadata).