Merge pull request #1 from erasmus-without-paper/mj

Initial release

CHANGELOG.md

@@ -0,0 +1,11 @@
+Release notes
+=============
+
+This document describes all the changes made to the *Interinstitutional Agreement Approval CNR API*
+document, starting from its first beta draft version.
+
+
+0.1.0
+-----
+
+Initial release.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Beneficiaries of the EWP projects: https://raw.githubusercontent.com/erasmus-without-paper/ewp-contributors/master/CONTRIBUTORS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,2 +1,96 @@
-# ewp-specs-api-iia-approval-cnr
-Specifications of EWP's Interinstitutional Agreement Approval CNR API
+Interinstitutional Agreement Approval CNR API
+=============================================
+
+* [What is the status of this document?][statuses]
+* [See the index of all other EWP Specifications][develhub]
+
+
+Summary
+-------
+
+This document describes the **Interinstitutional Agreement Approval CNR API**.
+This API can be implemented by all EWP partners, and will be called by some
+other EWP partners whenever related IIAs are approved by them. It allows
+the partners to listen for approvals of their copies of the IIAs.
+
+CNR stands for Change Notification Receiver. For a detailed introduction on how
+CNR APIs work, please read [this page][cnr-intro].
+
+
+Request method
+--------------
+
+ * Requests MUST be made with HTTP POST method. Servers MAY reject all other
+   request methods.
+
+
+Request parameters
+------------------
+
+Parameters MUST be provided in the regular `application/x-www-form-urlencoded`
+format.
+
+
+### `approving_hei_id` (required)
+
+Identifier of the HEI which has recently approved the partner's copy of the IIA
+and is now sending the notification about this event.
+
+Server implementers SHOULD verify if the request is signed with a proper client
+certificate bound to this HEI.
+
+
+### `owner_hei_id` (required)
+
+Identifier of the HEI which is the owner of the copy of the agreement, that has been approved.
+Together with `iia_id`, uniquely identifies the agreement copy.
+
+
+### `iia_id` (required)
+
+Partner's identifier of the IIA which has been approved. **Note:** this is NOT the ID assigned
+by the notifier (approving HEI), but by the owner of the copy which has been approved.
+
+
+Security
+--------
+
+This version of this API uses [standard EWP Authentication and Security, Version 2][sec-v2].
+Server implementers choose which security methods they support by declaring them
+in their Manifest API entry.
+
+
+Handling of invalid parameters
+------------------------------
+
+ * General [error handling rules][error-handling] apply.
+
+ * Servers MUST return a valid (HTTP 200) XML response whenever the request has
+   been [properly received][bad-cnr-request]. Unless HTTP 200 is received,
+   clients are RECOMMENDED to automatically retry the request after some time.
+
+
+Response
+--------
+
+Servers MUST respond with a valid XML document described by the
+[response.xsd](response.xsd) schema. See the schema annotations for further
+information.
+
+
+Keep in mind that...
+--------------------
+
+It is NOT guaranteed that all notifications will be delivered to you promptly.
+Some notifications may also **not reach you at all**. Also, not every server
+sends such notifications (look for `<sends-notifications/>` element in
+[IIAs Approval API][iias-approval-api]'s manifest entries to get a clue which servers do).
+
+
+[bad-cnr-request]: https://github.com/erasmus-without-paper/ewp-specs-architecture#bad-cnr-request
+[cnr-intro]: https://github.com/erasmus-without-paper/ewp-specs-architecture#cnr
+[develhub]: http://developers.erasmuswithoutpaper.eu/
+[error-handling]: https://github.com/erasmus-without-paper/ewp-specs-architecture#error-handling
+[iias-approval-api]: https://github.com/erasmus-without-paper/ewp-specs-api-iias-approval
+[sec-v2]: https://github.com/erasmus-without-paper/ewp-specs-sec-intro/tree/stable-v2
+[statuses]: https://github.com/erasmus-without-paper/ewp-specs-management#statuses

manifest-entry.xsd

@@ -0,0 +1,69 @@
+<?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:sec="https://github.com/erasmus-without-paper/ewp-specs-sec-intro/tree/stable-v2"
+    elementFormDefault="qualified"
+
+    targetNamespace="https://github.com/erasmus-without-paper/ewp-specs-api-iia-approval-cnr/blob/stable-v1/manifest-entry.xsd"
+    xmlns="https://github.com/erasmus-without-paper/ewp-specs-api-iia-approval-cnr/blob/stable-v1/manifest-entry.xsd"
+>
+    <xs:import
+        schemaLocation="https://raw.githubusercontent.com/erasmus-without-paper/ewp-specs-architecture/stable-v1/common-types.xsd"
+        namespace="https://github.com/erasmus-without-paper/ewp-specs-architecture/blob/stable-v1/common-types.xsd"
+    />
+
+    <xs:import
+        schemaLocation="https://raw.githubusercontent.com/erasmus-without-paper/ewp-specs-sec-intro/stable-v2/schema.xsd"
+        namespace="https://github.com/erasmus-without-paper/ewp-specs-sec-intro/tree/stable-v2"
+    />
+
+    <xs:annotation>
+        <xs:documentation>
+            This schema is a part of the Erasmus Without Paper project. Before you start
+            using it, make sure you have read the general rules described here:
+
+            http://developers.erasmuswithoutpaper.eu/
+        </xs:documentation>
+    </xs:annotation>
+
+    <xs:element name="iia-cnr">
+        <xs:annotation>
+            <xs:documentation>
+                If this element is present in EWP Host's manifest file, then the host states
+                that it implements the Interinstitutional Agreement Approval CNR API described here:
+
+                https://github.com/erasmus-without-paper/ewp-specs-api-iia-approval-cnr
+            </xs:documentation>
+        </xs:annotation>
+        <xs:complexType>
+            <xs:complexContent>
+                <xs:extension base="ewp:ManifestApiEntryBase">
+                    <xs:sequence>
+                        <xs:element name="http-security" type="sec:HttpSecurityOptions" minOccurs="0" maxOccurs="1">
+                            <xs:annotation>
+                                <xs:documentation>
+                                    Describes which security policies the server supports for this API. If not
+                                    given, then the server states that it supports the default set of security
+                                    policies (as described in the annotations in sec:HttpSecurityOptions).
+
+                                    Clients SHOULD consult this element before accessing the endpoint given in the
+                                    `url` element (otherwise, their request might be rejected by the server).
+                                </xs:documentation>
+                            </xs:annotation>
+                        </xs:element>
+                        <xs:element name="url" type="ewp:HTTPS" minOccurs="1" maxOccurs="1">
+                            <xs:annotation>
+                                <xs:documentation>
+                                    An URL at which the the host will be listening.
+                                </xs:documentation>
+                            </xs:annotation>
+                        </xs:element>
+                    </xs:sequence>
+                </xs:extension>
+            </xs:complexContent>
+        </xs:complexType>
+    </xs:element>
+
+</xs:schema>

response.xsd

@@ -0,0 +1,36 @@
+<?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"
+    elementFormDefault="qualified"
+
+    targetNamespace="https://github.com/erasmus-without-paper/ewp-specs-api-iia-approval-cnr/tree/stable-v1"
+    xmlns="https://github.com/erasmus-without-paper/ewp-specs-api-iia-approval-cnr/tree/stable-v1"
+>
+    <xs:import
+        schemaLocation="https://raw.githubusercontent.com/erasmus-without-paper/ewp-specs-architecture/stable-v1/common-types.xsd"
+        namespace="https://github.com/erasmus-without-paper/ewp-specs-architecture/blob/stable-v1/common-types.xsd"
+    />
+
+    <xs:annotation>
+        <xs:documentation>
+            This schema is a part of the Erasmus Without Paper project. Before you start
+            using it, make sure you have read the general rules described here:
+
+            http://developers.erasmuswithoutpaper.eu/
+        </xs:documentation>
+    </xs:annotation>
+
+    <xs:element name="iia-approval-cnr-response" type="ewp:Empty">
+        <xs:annotation>
+            <xs:documentation>
+                This describes the format of the response returned by the EWP Interinstitutional
+                Agreement Approval CNR API.
+
+                Currently CNR responses are always empty.
+            </xs:documentation>
+        </xs:annotation>
+    </xs:element>
+
+</xs:schema>