frangarcj / ewp-specs-api-iias

Specifications of EWP's Interinstitutional Agreements API.

Interinstitutional Agreements API

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

Summary

This document describes the Interinstitutional Agreements API. This API allows partners to compare their copies of interinstitutional Erasmus+ mobility agreements with each other, which makes it easier to spot errors. This API is complementary with the Interinstitutional Agreements Approval API where HEIs can approve agreements they exchange via the IIAs API.

Introduction

As part of the EWP project, we have thoroughly discussed many options of how to design the functionality of synchronizing IIAs between different HEIs. The IIAs API is the final result.

Features

• It is distributed. Agreements (IIAs) are stored and hosted only by the institutions involved in these agreements. If the institutions use the IIA Manager (part of the Dashboard), their agreements are stored in the Dashboard repository.

• All partners are equal. There is no "master" of the agreement. Since all partners of a single IIA are allowed to serve their copies of this IIA, therefore multiple conflicting copies of a single IIA may exist in the network. These conflicts are not resolved by the system itself, but our APIs allow partners to discover such conflicts early (so that they may fix them by themselves).

• No history of changes. This API will serve only a single copy of the agreement (with no history of previous versions). This copy should be the copy which is currently in use by the HEI which is serving the API.

Fact sheet information

If you compare our IIA XSDs to the official IIA template from the European Commission, for years 2021-20[29], you may notice that many fields seem to be missing in our XSDs. This is because we have decided to include many fields in the Institutions API and the Factsheet API instead.

Based on the official IIA template from the European Commission for years 2021-20[29], we follow the following rules:

• General information that is part of Higher Education Institutions’ profile and made publicly available to students is part of the Institutions API (and - in some cases - Organizational Units API) and the Factsheet API. The general information can be updated without formal approval of the partner.

• Data on the terms of agreement that needs to be approved by both partners is part of this API. The approval is done in the IIAs Approval API.

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.

Endpoints and functionality to be implemented

Server implementers MUST:

• Implement the get endpoint.
• Implement the index endpoint.
• Put the URLs of these endpoints in their manifest file, as described in manifest-entry.xsd.

The details on each of these endpoints are described on separate pages of this API specification (use the links above).

Implementers also MUST implement a Notification Sender for Interinstitutional Agreement objects. That means that an EWP host will try to deliver notifications to all Interinstitutional Agreement CNR APIs implemented throughout the EWP Network whenever related agreement objects are updated.

Data model entities involved in the response

• IIA
• IIA Partner
• Cooperation Condition
• Coordinator
• Person