Operation of the EWP network is based on the set of APIs. These APIs come in groups related to specific business processes, like handling inter-institutional agreements, learning agreements, nominations, etc. This grouping is described, and the description is supported by scenarios showing business and technical perspectives and sharing hints on implementation and good practices.
This document contains description of the GitHub repositories related to APIs. All active GitHub repositories of the EWP Network are documented on a separate page: Documents and specifications.
The document starts with the description of the API management cycle and rules of the API design and versioning.
Changes in API specifications
These are the most important stages and activities of the API management cycle:
Plan
The business analysts from the ESCI team identify all documents which create a legal and operational framework for the Erasmus+ mobility processes. Based on this, documents like Mandatory Business Requirements, Semantic Interoperability and User Guide for the designed processes are elaborated. Their role is to define the business goals and set up the business processes in the context of EWP. A roadmap is developed with a detailed plan of further steps, which sets a timeframe for development, testing & validation, and finally deployment in the production network.
Design and develop
The EWP technical team responsible for the API design maps new requirements and the involved processes into the sequence of API requests and responses, API query parameters, data formats of exchanged objects, error responses. They also define the scope of each API, i.e. plan out the capabilities and functionality that the APIs will provide, as well as any constraints or limitations.
First draft ideas are consulted with the internal technical groups from the ESCI team and then with the mobility software providers.
Draft specifications are posted in GitHub repositories where they can be consulted and reviewed by the technical teams. Also change proposals may be submitted in GitHub.
Documentation of the EWP APIs is hosted in GitHub. It contains general description of the API, formal XSD schemas, example XML responses, elaborated test scenarios, and other supporting documents (e.g. official templates, Mandatory Business Requirements).
When the detailed specifications are posted in GitHub, the mobility software providers may start implementing the APIs and the API design team may start developing API validators.
Test
The developed APIs are first tested locally by means of unit testing. Then APIs can be posted in the DEV EWP network. Here the API validators can be used for basic validation that APIs are conformant with the specification. Then teams of providers may test bilaterally. All aspects of the API should be tested: business logic, security, scalability, and compatibility.
Deploy
Once the APIs are developed and tested, in compliance with the regulations of the EWP network (see EWP entry procedure and Technical testing and validation site), they can be deployed in the production network. This deployment stage involves coordinating the process, setting up monitoring and logging, and checking the APIs in the target environment to ensure everything is running smoothly.
Maintain
Maintenance is an ongoing activity and involves monitoring API’s performance, fixing bugs, and releasing updates to keep an API running smoothly. The EWP Monitoring system allows to track behaviour of the nodes in real time in the production network, identify misbehaving nodes and counteract.
Retire
Business goals change, new priorities arise, requirements get reformulated or change priority, technical needs may require change in the network architecture. For such reasons, an API may reach the end of its useful life and needs to be retired. There is a well-defined process in place to ensure a smooth and orderly transition, which includes decommissioning an API, removing all dependencies, and notifying transition plans to API users.
According to the currently agreed rule, upgrades of the existing APIs taking into account new requirements should not happen more often than once a year.
Rules of API design and versioning
In the EWP project Semantic Versioning is used for releases of EWP technical documentation:
Documents get version numbers only after they are officially approved.
Semantic versioning scheme allows developers to easily determine when a breaking change occurs in a particular API.
It follows a set of explicit rules.
Here is the summary of the numbering schema. Given a version number MAJOR.MINOR.PATCH, increment the:
MAJOR version when you make incompatible API changes.
MINOR version when you add functionality in a backward compatible manner.
PATCH version when you make backward compatible bug fixes.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in specifications are to be interpreted as described in RFC 2119 when, and only when, they appear in all capitals, as shown here.
Once a document is released, every subsequent release of such document MUST be accompanied by a changelog. All changes SHOULD be noted in this changelog (and backward-incompatible changes should be additionally highlighted).
Primary network APIs
Discovery manifest API
Discovery manifest files serve to announce which HEIs your system covers, which features (APIs) you have implemented, and which credentials your clients are going to use when fetching the data from the EWP network.
Echo API
Echo API is used to design and test the authentication and security framework of the network.
Registry API
This API is implemented by the EWP Registry Service and it returns the catalogue file with information gathered from the manifest files.
General purpose APIs
Institutions and faculties
Institutions API allows external clients to retrieve general information on institutions either covered, or otherwise known, by the host. This information includes things like address, logo image and key contact persons.
Organizational Units API allows external clients to retrieve general information on selected organizational units (faculties, departments, divisions, etc.) either covered, or otherwise known by the host. It responds with a similar type of information as Institutions API does, but on a lower level.
Courses
Courses API allows other HEIs to access information on courses and other learning opportunities conducted in a given HEI.
Simple Course Replication API allows the clients to replicate the catalogue of courses conducted on this HEI. This in turn allows the clients to design rich course searching user experience.
File API
This API allows partners to share files securely.
Monitoring API
This API allows clients in the EWP network to inform the network's administrators about any issues encountered when making requests.
EWP mobility process explained
With help of some flowcharts, this document describes how the Student Mobility Business Process is modelled within the EWP network.
Erasmus mobility APIs - Inter-institutional agreements API
Inter-institutional agreements API
This API allows partners to compare their copies of inter-institutional Erasmus+ mobility agreements with each other, which makes it easier to spot errors. This API is complementary with the Inter-institutional agreements approval API where HEIs can approve agreements they exchange via the IIAs API.
Inter-institutional agreements CNR API
This API allows the partners to listen for changes in other copies of their IIAs kept in the EWP network.
Inter-institutional agreements Approval API
This API allows HEIs to approve agreements sent by their partners in the Inter-institutional agreements API.
Inter-institutional agreements Approval CNR API
This API allows the partners to listen for approvals of their copies of the IIAs.
Mobility Factsheet API
This API allows partners to share all the information useful for incoming students in the mobility process.
Erasmus mobility APIs - Outgoing Mobilities (Nominations and LAs)
Outgoing Mobilities API
This API is implemented by the sending institution. It allows the receiving HEI to read, write and enumerate mobilities stored on the sending HEI's servers.
Outgoing Mobility Learning Agreements API
This API is implemented by the sending institution. It allows the receiving HEI to read and accept learning agreements stored on the sending HEI's servers and propose changes to them. This API is based on the official LA template.
Outgoing Mobility CNR API
This API is implemented by the receiving institution if it wants to be notified whenever mobilities kept on their partner institutions' servers are changed.
Outgoing Mobility Learning Agreements CNR API
This API is implemented by the receiving institution if it wants to be notified whenever learning agreements kept on their partner institutions' servers are changed.
Erasmus mobility APIs - Incoming Mobilities (Nominations and ToRs)
Incoming Mobilities API
This API is implemented by the receiving institution. It allows the sending HEI to read the receiving HEI's part of the information related to the sending HEIs outgoing mobilities.
Incoming Mobility CNR API
This API is implemented by the sending institution if it wants to be notified whenever incoming mobilities kept on their partner institutions' servers are changed.
Incoming Mobility ToR API
This API is implemented by the receiving institution. It allows the sending institution to retrieve Transcripts of Records issued by the receiving institution for a given set of mobility IDs.
Incoming Mobility ToR 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.
Beneficiary Module Mobilities API
This API is implemented by only one host managed by the Directorate-General Education and Culture Unit (DG EAC) of the European Commission. It allows external clients to automatise reporting of individual mobilities of students to the Beneficiary Module.
EWP Student Service Providers API
This API provides a structured overview about the available student services at the receiving institution.