Skip to content

Latest commit

 

History

History
101 lines (66 loc) · 3.52 KB

index.md

File metadata and controls

101 lines (66 loc) · 3.52 KB

IIA Index endpoint

Summary

This endpoint allows clients to see the list of all agreements (IIAs) known to a particular HEI.

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 either in a query string (for GET requests), or in the application/x-www-form-urlencoded format (for POST requests).

receiving_academic_year_id (optional, repeatable)

If given, then the server SHOULD limit the list of returned IIA IDs to only such, which are valid in at least one of the given academic years.

In other words, if we are called with the following parameters:

receiving_academic_year_id=2005/2006&receiving_academic_year_id=2006/2007

Then, if for agreement A none of these academic years are between the <receiving-first-academic-year-id> and <receiving-last-academic-year-id> in any of its cooperation conditions, then A SHOULD NOT be included in the response.

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 IIA IDs to the ones that have been either created or modified after the given point in time.

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

  • Servers MAY ignore the modified_since parameter completely, and always respond with the full list of IIA IDs. (If, for some reason, the server cannot reliably identify when IIAs are updated, then it's even better to do so.)

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

Permissions

You MUST return the set of all IDs that the requester has access to (via the get endpoint). See the get endpoint for details on which IIAs should be accessible by which requester.

Handling of invalid parameters

Response

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