Skip to content

Latest commit

 

History

History
142 lines (97 loc) · 5.48 KB

index.md

File metadata and controls

142 lines (97 loc) · 5.48 KB
Raw

Outgoing Mobilities Index endpoint

Summary

This endpoint allows the receiving institution to access a list of all mobilities it can read on the sending institution's server.

Request method

  • Requests MUST be made with either HTTP GET or HTTP POST method. Servers MUST support both these methods. Servers SHOULD reject all other request methods.

  • Clients are advised to use POST when passing large number of parameters (servers MAY set a limit on their GET query string length).

Request parameters

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

sending_hei_id (required)

An identifier of the institution which is the sending partner of the mobilities. This parameter MUST be required by the server even if it covers only a single institution. It is not repeatable.

By default, the server returns all mobilities the requester has access to (regardless of their receiving partner, arrival date, nor status). This includes very old mobilities, and the cancelled ones.

receiving_hei_id (repeatable, optional)

A list of institution identifiers. If given, then the results returned MUST contain only those mobilities whose receiving institution matches at least one of the given receiving_hei_id identifiers.

This parameter is repeatable, so the request MAY contain multiple occurrences of it. The server is REQUIRED to process all of them.

receiving_academic_year_id (optional)

An academic year identifier, in the YYYY/YYYY format, as defined in the EWP Academic Term Data Types document. If given, then the server MUST return only such mobilities which have taken place (or are planned to take place) during this single academic year.

This parameter was added to allow the client to synchronize only a smaller subset of all mobilities more easily (because many clients don't want to store mobilities which have ended long ago).

modified_since (optional)

A datetime string in the xs:dateTime format, e.g. 2004-02-12T15:19:21+01:00.

If given, then the server SHOULD filter the returned mobility IDs to the ones which have been either created or modified after the given point in time.

  • Servers MAY include mobilities which were not modified. For example, if the server only suspects that the mobility has been modified, then it is okay to include such mobility's ID in the response.

  • As we previously explained here, clients MAY use the index and get endpoints as a pull-based method of synchronization, alternative (or rather complementary) to CNRs. It is RECOMMENDED for the servers to support this parameter, to avoid unnecessary network traffic.

Permissions

Only selected Outgoing Mobility objects should be accessible to the caller. Visibility of objects SHOULD be kept in sync with the visibility described in the get endpoint. That is:

  • Servers MUST publish IDs of every mobility which is accessible (to the same caller) via the get endpoint.

  • Server MUST NOT publish IDs of objects which would NOT be accessible (to the same caller) via its get endpoint. Clients which receive mobility IDs from the index endpoint should be able to fetch all objects referenced by those IDs.

Handling of invalid parameters

  • General error handling rules apply.

  • Note, that parameters are "AND-ed" together, but their values are "OR-ed". This means that invalid or unknown values provided in sending_hei_id and receiving_hei_id parameters MUST be allowed (but not ignored) by the server.

    The difference between "being allowed" and "being ignored" becomes clear once you try to analyze the scenario when one of these lists contains only such IDs which are unknown to the server. The server MUST respond with an empty <response> element in this case, regardless of all the other parameters. For example:

    • ?sending_hei_id=known&receiving_hei_id=known&receiving_hei_id=UNKNOWN will return some results,
    • ?sending_hei_id=known&receiving_hei_id=known will return exactly the same results,
    • ?sending_hei_id=known&receiving_hei_id=UNKNOWN will NEVER return any results,
    • ?sending_hei_id=known will return results again (but not necessarily the same results as the ones returned in the first two bullets).

Response

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