Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'stable-v1-review' into stable-v1
- Loading branch information
Showing
11 changed files
with
1,433 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,134 @@ | ||
| Release notes | ||
| ============= | ||
|
|
||
| This document describes all the changes made to the *Interinstitutional | ||
| Agreements API* document, starting from its first beta draft version. | ||
|
|
||
|
|
||
| 1.0.0 | ||
| ----- | ||
|
|
||
| * First stable release! | ||
| * Clean up: Replaced all relative schemaLocations with absolute ones. | ||
|
|
||
|
|
||
| 0.9.0 | ||
| ----- | ||
|
|
||
| * Changed XML namespaces (as part of | ||
| [this issue](https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/22)). | ||
| Since this version, this API is in the `stable-v1` XML namespace. | ||
|
|
||
|
|
||
| 0.8.1 | ||
| ----- | ||
|
|
||
| * Minor fixes in XSD's "style". | ||
|
|
||
|
|
||
| 0.8.0 | ||
| ----- | ||
|
|
||
| * New parameter in the `index` endpoint: `modified_since`. It is RECOMMENDED | ||
| for the servers to support this parameter, to avoid unnecessary network | ||
| traffic. | ||
|
|
||
|
|
||
| 0.7.0 | ||
| ----- | ||
|
|
||
| * `total-days` and `total-months` were introduced as a valid alternative to | ||
| `avg-days` and `avg-months` | ||
| ([why?](https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/17)). | ||
|
|
||
|
|
||
| 0.6.0 | ||
| ----- | ||
|
|
||
| * New request parameter: `partner_hei_id`. (Servers are required to support | ||
| it.) | ||
|
|
||
|
|
||
| 0.5.0 | ||
| ----- | ||
|
|
||
| * Academic Term and Abstract Contact data types are now in `stable-v1` | ||
| namespace | ||
| ([more information](https://github.com/erasmus-without-paper/general-issues/issues/24)). | ||
|
|
||
| * Introduced limits on IIA ID values | ||
| ([more information](https://github.com/erasmus-without-paper/general-issues/issues/23)). | ||
|
|
||
| * `minOccurs` and `maxOccurs` are now provided explicitly | ||
| ([why?](https://github.com/erasmus-without-paper/general-issues/issues/22)). | ||
|
|
||
|
|
||
| 0.4.0 | ||
| ----- | ||
|
|
||
| Major changes in document structure: | ||
|
|
||
| * Optional `<ounit-id>` element has been added for each partner. The | ||
| `<partner-hei>` element has been renamed to `<partner>` (because a partner | ||
| can now refer to an Organizational Unit, not only a HEI). See | ||
| [this thread](https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/11). | ||
|
|
||
| * All the elements describing the "local partner" were removed. The local | ||
| partner is now described the same way any other partner is - via the | ||
| `<partner>` element (the first of them, to be exact). See | ||
| [this thread](https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/13). | ||
|
|
||
| Other changes: | ||
|
|
||
| * New `iia_code` parameter was added to allow requesters searching for IIAs | ||
| by their codes (the server is now REQUIRED to support this parameter). | ||
| Providing `iia_id` parameter is no longer required, if the requester provides | ||
| the `iia_code` parameter instead. This is a part of a larger change in all | ||
| APIs described | ||
| [here](https://github.com/erasmus-without-paper/general-issues/issues/21). | ||
|
|
||
| * Start and end dates were removed. They MAY return again, if we can define | ||
| more clearly what they mean and what they can be used for (by the client). | ||
| Discuss [here](https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/10). | ||
|
|
||
| * Clarified which IIAs should be accessible by whom. Clarified what servers | ||
| should do if in their model the *end date* of a cooperation condition can be | ||
| unspecified. | ||
|
|
||
| * Modified the `<contact>` elements in examples to fit recent additions to the | ||
| [Abstract Contact Type](https://github.com/erasmus-without-paper/ewp-specs-types-contact). | ||
|
|
||
|
|
||
| 0.3.0 | ||
| ----- | ||
|
|
||
| * New required `<iia-code>` element. Together with `<iia-id>` it allows server | ||
| implementers to provide both surrogate and natural/business keys for all | ||
| IIAs. Examples were updated appropriately to visualize the difference between | ||
| them. See [this thread](https://github.com/erasmus-without-paper/ewp-specs-api-mobilities/issues/9#issuecomment-271272493) | ||
| for more reasoning. | ||
|
|
||
| * The `<isced-code>` element was renamed to `<isced-f-code>` | ||
| ([why?](https://github.com/erasmus-without-paper/ewp-specs-api-mobilities/issues/8#issuecomment-270402114)). | ||
|
|
||
| * New `<signing-date>` elements (one per each partner, as requested | ||
| [here](https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/7)). | ||
|
|
||
| * Explained the meaning of `<in-effect>` in more detail (see | ||
| [this issue](https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/9)). | ||
|
|
||
| * Explained from where the clients should fetch information on external HEIs | ||
| and organization units (in particular, the ones which are not part of EWP | ||
| yet). See [this thread](https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/6). | ||
|
|
||
|
|
||
| 0.2.0 | ||
| ----- | ||
|
|
||
| * Added a missing `<max-iia-ids>` element to `manifest-entry.xsd`. | ||
|
|
||
|
|
||
| 0.1.0 | ||
| ----- | ||
|
|
||
| Initial release. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,132 @@ | ||
| Interinstitutional Agreements API | ||
| ================================= | ||
|
|
||
| * [What is the status of this document?][statuses] | ||
| * [See the index of all other EWP Specifications][develhub] | ||
|
|
||
|
|
||
| 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. | ||
|
|
||
|
|
||
| Introduction | ||
| ------------ | ||
|
|
||
| As part of the EWP project, we have | ||
| [thoroughly discussed](https://github.com/erasmus-without-paper/general-issues/issues/12) | ||
| [many options](https://github.com/erasmus-without-paper/general-issues/issues/12#issuecomment-229931282) | ||
| of how to design the functionality of synchronizing IIAs between different | ||
| HEIs. We have proposed multiple solutions, and then rejected them, either | ||
| because of their limited functionality, or their complexity. | ||
|
|
||
| This document describes the solution we ended up agreeing to. | ||
|
|
||
|
|
||
| ### It is not (!) required in EWP mobility flow | ||
|
|
||
| The most important feature to understand about this solution, is that HEIs are | ||
| not required to neither *serve* nor *use* this API. | ||
|
|
||
| This API is *not* part of the primary mobility flow modeled in EWP. You can | ||
| still exchange information on Nominations and Learning Agreements **without** | ||
| implementing this API. It serves *only* as a helper API to spot differences | ||
| between IIAs. If you choose to implement it, then **you should probably | ||
| implement it after all the other APIs**. | ||
|
|
||
| * **Why not required?** IIA is an official document. Therefore, it seems | ||
| reasonable to assume that: | ||
|
|
||
| - Each of the partners possesses a *printed copy* of this document. | ||
| - Their computer systems are somewhat aware of the data contained within. | ||
| - This data is **usually** correct (in sync with the partner's copy). | ||
|
|
||
| Other EWP APIs will refer to IIA **IDs** (and **IDs only**). This means | ||
| that, although all partners might need to exchange these IDs, they still are | ||
| allowed to simply assume that their own local copy of this IIA is correct | ||
| (and it **usually** is). | ||
|
|
||
| * **Why would I want to implement it then?** Because we can do better than | ||
| "usually" (see the sentences above). If we expose our agreements to the | ||
| other partner via an API, then the partner will be able to compare the | ||
| contents more easily, and possibly **find differences** in an automated way. | ||
| In the future, when new agreements are forged, it might also enable the | ||
| partner to copy the agreement's data directly from one computer system to | ||
| another, without the need of typing it by hand. | ||
|
|
||
|
|
||
| ### Other features | ||
|
|
||
| * **It is distributed**. Agreements (IIAs) are stored and hosted **only** by | ||
| the institutions involved in these agreements. No agreements are stored on | ||
| central servers at any time. | ||
|
|
||
| * **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. | ||
|
|
||
|
|
||
| ### Where are the fact sheets? | ||
|
|
||
| If you compare our IIA XSDs to EUC IIA templates, 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][institutions-api] instead. | ||
|
|
||
| We *tried* to follow the following rules: | ||
|
|
||
| * We were aiming for IIAs API to describe only such data, which "belongs to" | ||
| (and is often stored by) *all* IIA partners, whereas Institutions API and | ||
| Organizational Units API describe data which "belongs to" a *single* partner | ||
| only (and other partners often don't really need to store it). | ||
|
|
||
| * Data which is public, and can be changed without signing the IIA again, has | ||
| been made part of the Institutions API (and - in some cases - Organizational | ||
| Units API). Data which is not necessarily public, and which can be changed | ||
| only after the IIA is signed again, has been made part of the IIAs API. | ||
|
|
||
| As you can see, these are NOT very strict nor explicit rules. And also, we did | ||
| not necessarily follow them to the letter. As a result, sometimes it might not | ||
| be obvious where a particular piece of data can be found, but - once you get | ||
| to know the model - all should gradually become clear. | ||
|
|
||
|
|
||
| Endpoints to be implemented | ||
| --------------------------- | ||
|
|
||
| Server implementers MUST: | ||
|
|
||
| * Implement the [`get` endpoint](endpoints/get.md). | ||
| * Implement the [`index` endpoint](endpoints/index.md). | ||
| * Put the URLs of these endpoints in their [manifest file][discovery-api], as | ||
| described in [manifest-entry.xsd](manifest-entry.xsd). | ||
|
|
||
| The details on each of these endpoints are described on separate pages of this | ||
| API specification (use the links above). | ||
|
|
||
|
|
||
| Data model entities involved in the response | ||
| -------------------------------------------- | ||
|
|
||
| * IIA | ||
| * IIA Partner | ||
| * Cooperation Condition | ||
| * Coordinator | ||
| * Person | ||
|
|
||
|
|
||
| [develhub]: http://developers.erasmuswithoutpaper.eu/ | ||
| [statuses]: https://github.com/erasmus-without-paper/ewp-specs-management#statuses | ||
| [discovery-api]: https://github.com/erasmus-without-paper/ewp-specs-api-discovery | ||
| [echo]: https://github.com/erasmus-without-paper/ewp-specs-api-echo | ||
| [error-handling]: https://github.com/erasmus-without-paper/ewp-specs-architecture#error-handling | ||
| [institutions-api]: https://github.com/erasmus-without-paper/ewp-specs-api-institutions |
Oops, something went wrong.