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.
| Note |
|---|
The list of APIs with links to all versions is still available in the Developers Guide, but this page will eventually be removed. |
| Table of Contents |
|---|
API Versioning
The following status labels are used for released APIs:
...
| Status | ||||
|---|---|---|---|---|
|
...
| Status | ||
|---|---|---|
|
...
| Status | ||
|---|---|---|
|
| Status | ||||
|---|---|---|---|---|
|
...
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.
...
| Table of Contents |
|---|
...
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
...
This API is implemented by the EWP Registry Service and it returns the catalogue file with information gathered from the manifest files.
EWP mobility process explained
With help of some flowcharts, this document describes how the Student Mobility Business Process is modelled within the EWP network.
...
General purpose APIs
Institutions and faculties
...
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
...