Skip to content

Commit

Permalink
Merge pull request #19 from erasmus-without-paper/new-la-template
Browse files Browse the repository at this point in the history 
Update API to the new LA template
  • Loading branch information
@mkurzydlowski
mkurzydlowski authored Feb 22, 2021
2 parents f0a6f27 + 23aadcf commit 67a63dc
Show file tree
Hide file tree
Showing 38 changed files with 1,180 additions and 1,110 deletions.
15 changes: 9 additions & 6 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,14 @@ Outgoing Mobility Learning Agreements API
Summary
-------

**NOTE: This API is being updated in order to ensure compatibility with the OLA.
Until a stable version is available, developers are advised to not implement
the current API version.**

This document describes the **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 new LA template. The most recent version is available
on the [EUF Wiki][new-la-template].


Reminder on vocabulary
----------------------
Expand Down Expand Up @@ -48,8 +47,8 @@ implementers to decide which methods are "secure enough". These recommendations
MAY change in the future.


Endpoints to be implemented
---------------------------
Endpoints and functionality to be implemented
---------------------------------------------

Server implementers MUST:

Expand All @@ -62,6 +61,9 @@ Server implementers MUST:
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 Learning Agreement objects.
That means that an EWP host will *try* to deliver notifications to all Outgoing Mobility Learning Agreement CNR APIs
implemented throughout the EWP Network whenever related mobility objects are updated.

Outgoing Mobility Learning Agreements API vs. Outgoing Mobilities API
---------------------------------------------------------------------
Expand Down Expand Up @@ -92,3 +94,4 @@ Data model entities involved in the response
[statuses]: https://github.com/erasmus-without-paper/ewp-specs-management#statuses
[discovery-api]: https://github.com/erasmus-without-paper/ewp-specs-api-discovery
[sec-v2]: https://github.com/erasmus-without-paper/ewp-specs-sec-intro/tree/stable-v2
[new-la-template]: https://wiki.uni-foundation.eu/display/EWP/New+LA+template
584 changes: 260 additions & 324 deletions endpoints/get-response.xsd
View file

Large diffs are not rendered by default.

14 changes: 14 additions & 0 deletions endpoints/get.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,9 @@ Server implementers provide their own chosen value of `<max-omobility-ids>` via
their manifest entry (see [manifest-entry.xsd](manifest-entry.xsd)). Clients
SHOULD parse this value (or assume it's equal to `1`).

Note: Each outgoing mobility should have at most one learning agreement.
Extensions to a learning agreement should be handled by its modification.


Permissions
-----------
Expand Down Expand Up @@ -109,6 +112,17 @@ Servers MUST respond with a valid XML document described by the
further information.


Virtual components
------------------

For semester(s) and short-term doctoral mobilities the LA template requires to fill a "virtual component" flag.
This flag is assumed to be checked only if:
* For semester(s) mobility there is a non-empty list of `virtual-components` with at least one component having `status`
attribute other than `deleted`,
* For short-term doctoral mobility at least one component in `short-term-doctoral-components` has a non-empty
`short-description`.


[develhub]: http://developers.erasmuswithoutpaper.eu/
[statuses]: https://github.com/erasmus-without-paper/ewp-specs-management#statuses
[omobilities]: https://github.com/erasmus-without-paper/ewp-specs-api-omobilities
Expand Down
17 changes: 16 additions & 1 deletion endpoints/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ Summary
This endpoint allows the receiving institution to access a list of all
learning agreements it can read on the sending institution's server.

Only learning agreements currently approved by the student and the sending HEI should be returned.


Request method
--------------
Expand Down Expand Up @@ -58,6 +60,19 @@ document. If given, then the server MUST return learning agreements for only suc
which have taken place (or are planned to take place) during this single academic year.


### `global_id` (optional)

Global student identifier. Should follow the specification of the
[European Student Identifier](https://wiki.geant.org/display/SM/European+Student+Identifier).
If given, then the server MUST return learning agreements belonging to the specified student.


### `mobility_type` (optional)

One of the following mobility types: `blended`, `doctoral`, `semester`.
If given, then the server MUST return learning agreements only of the specified type.


### `modified_since` (optional)

A datetime string in the [`xs:dateTime` format][xs-datetime], e.g.
Expand All @@ -72,7 +87,7 @@ for which the learning agreement has been either created or modified after the g

* As we previously explained [here][index-pulling], clients MAY use the
`index` and `get` endpoints as a pull-based method of synchronization,
alternative (or rather complementary) to CNRs. It is RECOMMENDED for the
complementary to CNRs. It is RECOMMENDED for the
servers to support this parameter, to avoid unnecessary network traffic.


Expand Down
107 changes: 32 additions & 75 deletions endpoints/update-request.xsd
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xml="http://www.w3.org/XML/1998/namespace"
xmlns:ewp="https://github.com/erasmus-without-paper/ewp-specs-architecture/blob/stable-v1/common-types.xsd"
xmlns:la="https://github.com/erasmus-without-paper/ewp-specs-api-omobility-las/blob/stable-v1/endpoints/get-response.xsd"
elementFormDefault="qualified"
Expand Down Expand Up @@ -49,12 +48,10 @@
<xs:documentation>
One request contains exactly one update element. But there are many possible
types of this update element.

Servers publish the list of supported update in their manifest entry.
</xs:documentation>
</xs:annotation>
<xs:element ref="approve-components-studied-proposal-v1"/>
<xs:element ref="update-components-studied-v1"/>
<xs:element ref="approve-proposal-v1"/>
<xs:element ref="comment-proposal-v1"/>
<!--
Note for future XSD designers: When adding new types here, remember to add them
in the manifest-entry.xsd file too.
Expand All @@ -64,12 +61,11 @@
</xs:complexType>
</xs:element>

<xs:element name="approve-components-studied-proposal-v1">
<xs:element name="approve-proposal-v1">
<xs:annotation>
<xs:documentation>
This request is sent by the receiving HEI when it wants to approve the
`latest-proposal` version of components-studied. For many HEIs, this
approval has the same meaning as "signing" this section of the LA.
This request is sent by the receiving HEI when it wants to approve the `changes-proposal`.
This approval has the same meaning as "signing" the LA.
</xs:documentation>
</xs:annotation>
<xs:complexType>
Expand All @@ -79,51 +75,41 @@
<xs:documentation>
ID of the mobility/learning agreement which this update request is about.

The sending partner of this mobility MUST match the partner provided in
`sending-hei-id`.
The sending partner of this mobility MUST match the partner provided in `sending-hei-id`.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="approving-party" minOccurs="1" maxOccurs="1" type="la:ApprovingParty">
<xs:element name="changes-proposal-id" type="xs:string" minOccurs="1" maxOccurs="1">
<xs:annotation>
<xs:documentation>
The party which is approving. In almost all cases, this will be
`receiving-hei`, but in some use cases it MAY also be `student` (if the
student is allowed to use receiving HEI's UI to approve Learning
Agreements).
Identifier of the current state of the `changes-proposal`, which is also the state which
is being approved. This element is required here to prevent edit conflicts:

The server MUST verify this value (it MUST NOT assume that it always equals
`receiving-hei`). If remote approval by this party is unsupported by this
server, HTTP 400 response MUST be returned, with proper user-message (e.g.
"University of Warsaw requires its students to approve their Learning
Agreements via local USOSweb system. It is not allowed to approve them
remotely.").
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="latest-proposal-id" minOccurs="1" maxOccurs="1" type="xs:string">
<xs:annotation>
<xs:documentation>
Identifier of the current state of the `latest-proposal`, which is also the state which
is being approved. This element is required here to prevent edit conflicts.
The server MUST verify it, in similar way as it's described in `update-components-studied-v1`.
https://en.wikipedia.org/wiki/Edit_conflict

The client - the receiving HEI - extracts this identifier from the response of the
Outgoing Mobility Learning Agreements API's `get` endpoint served at the sending HEI.

If the content of `changes-proposal-id` does not match the current
values as kept in the server's database, then the server MUST respond with
HTTP 409 error response.
https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10

Error response SHOULD include the `user-message` element with a brief
explanation (e.g. "Your copy of the Learning Agreement is not up-to-date.
Please refresh your copy from our servers and repeat your request.").
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="signature" type="la:Signature" minOccurs="1" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
</xs:element>

<xs:element name="update-components-studied-v1">
<xs:element name="comment-proposal-v1">
<xs:annotation>
<xs:documentation>
This request is sent by the receiving HEI when it want to suggest changes in
the `components-studied` section of the learning agreement object.

The sending HEI, on whose servers the learning agreement object is stored, MAY allow for
the receiving HEI to change `components-studied` freely, but it also MAY keep
these changes "on the side", and require a human to review them (e.g. a Sending
Coordinator, or a student).
This request is sent by the receiving HEI when it want to comment on a `changes-proposal`.
</xs:documentation>
</xs:annotation>
<xs:complexType>
Expand All @@ -133,55 +119,26 @@
<xs:documentation>
ID of the mobility/learning agreement which this update request is about.

The sending partner of this mobility MUST match the partner provided in
`sending-hei-id`.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="latest-proposal-id" type="xs:string" minOccurs="1" maxOccurs="1">
<xs:annotation>
<xs:documentation>
Identifier of the current state of the `latest-proposal`, which is
the *base for the suggested changes*. It is required here to prevent edit conflicts:

https://en.wikipedia.org/wiki/Edit_conflict

The client - the receiving HEI - extracts this element from the response of the
Outgoing Mobility Learning Agreements API's `get` endpoint served at the sending HEI.

If the content of `latest-proposal-id` does not match the current
values as kept in the server's database, then the server MUST respond with
HTTP 409 error response.
https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10

Error response SHOULD include the `user-message` element with a brief
explanation (e.g. "Your copy of the Learning Agreement is not up-to-date. We
are unable to process your suggestions because we lack a common base for
comparison. Please refresh your copy from our servers and repeat your request.").
The sending partner of this mobility MUST match the partner provided in `sending-hei-id`.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="suggestion" minOccurs="0" maxOccurs="1" type="la:ListOf_ComponentsStudied">
<xs:element name="changes-proposal-id" type="xs:string" minOccurs="1" maxOccurs="1">
<xs:annotation>
<xs:documentation>
This is the "target" version which the requester is aiming for.
It is RECOMMENDED to provide reasons for changes.

You MUST provide a suggestion or a comment (or both).
Identifier of the current state of the `changes-proposal`, which is being commented.
This element is required here to prevent edit conflicts as in `approve-proposal-v1`.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="comment" minOccurs="0" maxOccurs="1" type="xs:string">
<xs:element name="comment" type="xs:string" minOccurs="1" maxOccurs="1">
<xs:annotation>
<xs:documentation>
In the comment you can describe why LA has not been accepted and what are
the suggestions for changes. If the suggestion is possible to be expressed
in a structured way, it is RECOMMENDED to send the "suggestion" element.

You MUST provide a suggestion or a comment (or both).
Field to describe why LA has not been accepted and what are the suggested changes.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="signature" type="la:Signature" minOccurs="1" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Expand Down
Loading

0 comments on commit 67a63dc

Please sign in to comment.