From 9d7c5d115ea3ad0aaadcc03fba692235396d4c65 Mon Sep 17 00:00:00 2001 From: MBala98 Date: Mon, 25 Jul 2022 16:50:43 +0200 Subject: [PATCH 1/6] Add first version of stats endpoint --- README.md | 1 + endpoints/stats-response-example.xml | 19 ++++++++ endpoints/stats-response.xsd | 70 ++++++++++++++++++++++++++++ endpoints/stats.md | 64 +++++++++++++++++++++++++ 4 files changed, 154 insertions(+) create mode 100644 endpoints/stats-response-example.xml create mode 100644 endpoints/stats-response.xsd create mode 100644 endpoints/stats.md diff --git a/README.md b/README.md index a6a7f82..0e1a926 100644 --- a/README.md +++ b/README.md @@ -96,6 +96,7 @@ Server implementers MUST: * Implement the [`get` endpoint](endpoints/get.md). * Implement the [`index` endpoint](endpoints/index.md). + * Implement the [`stats` endpoint](endpoints/stats.md) * Put the URLs of these endpoints in their [manifest file][discovery-api], as described in [manifest-entry.xsd](manifest-entry.xsd). diff --git a/endpoints/stats-response-example.xml b/endpoints/stats-response-example.xml new file mode 100644 index 0000000..8f8f884 --- /dev/null +++ b/endpoints/stats-response-example.xml @@ -0,0 +1,19 @@ + + + + 0 + + 0 + 0 + 0 + 2022-07-10T09:00:00 + + diff --git a/endpoints/stats-response.xsd b/endpoints/stats-response.xsd new file mode 100644 index 0000000..2b32551 --- /dev/null +++ b/endpoints/stats-response.xsd @@ -0,0 +1,70 @@ + + + + + + + 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/ + + + + + + + This describes the format of the response returned by the `stats` endpoint of + EWP Interinstitutional Agreements API + + + + + + + + Number of IIAs created in the local system which can be fetched by the partner HEI. + + + + + + + Number of IIAs created in the local system which have been approved by the partner HEI, + but the matching copies of the partner have not been approved by the local HEI. + + + + + + + Number of IIAs created in the local system which have not been approved by the partner HEI, + but the matching copies of the partner have been approved by the local HEI. + + + + + + + Number of IIAs created in the local system which have been approved by the partner HEI + and the matching copies of the partner have been approved by the local HEI + + + + + + + The exact time at which these statistics were calculated. + + + + + + + diff --git a/endpoints/stats.md b/endpoints/stats.md new file mode 100644 index 0000000..d383fad --- /dev/null +++ b/endpoints/stats.md @@ -0,0 +1,64 @@ +IIA Stats endpoint +================ + +* [What is the status of this document?][statuses] +* [See the index of all other EWP Specifications][develhub] + + +Summary +------- + +This endpoint allows the client to get the statistics describing IIAs from a specific HEI. + +Request method +-------------- + + * Requests MUST be made with either HTTP GET or HTTP POST method. Servers MUST + support both these methods. Servers SHOULD reject all other request methods. + +Request parameters +------------------ + +Parameters MUST be provided either in a query string (for GET requests), or in +the `application/x-www-form-urlencoded` format (for POST requests). + + +### `hei_id` (required) + +Identifier of the HEI to gather IIAs statistics from. + +Response time +----------- + +Server SHOULD respond as fast as possible. This is why it is recommended to calculate statistics offline, rather than on request. +If the statistics are calculated offline, server MUST refresh them at least once a month. +It's also a reason why calculation date is included in the response. + + +Permissions +----------- + +Server SHOULD make this endpoint public. Server MUST allow EWP-Stats portal node to access this endpoint (TODO: to be verified) + + +Handling of invalid parameters +------------------------------ + + * General [error handling rules][error-handling] apply. + + * Invalid `hei_id` values (i.e. references to HEIs which are not covered by + this host) MUST result in a HTTP 400 error. + +Response +-------- + +Servers MUST respond with a valid XML document described by the +[stats-response.xsd](stats-response.xsd) schema. See the schema annotations for +further information. + + +[develhub]: http://developers.erasmuswithoutpaper.eu/ +[statuses]: https://github.com/erasmus-without-paper/ewp-specs-management#statuses +[iias-api]: https://github.com/erasmus-without-paper/ewp-specs-api-iias +[echo]: https://github.com/erasmus-without-paper/ewp-specs-api-echo +[error-handling]: https://github.com/erasmus-without-paper/ewp-specs-architecture#error-handling From 48c4c03083726f2fdd55dd23c40350afe3468e71 Mon Sep 17 00:00:00 2001 From: MBala98 Date: Mon, 25 Jul 2022 23:45:09 +0200 Subject: [PATCH 2/6] Improved stats endpoint --- endpoints/stats-response-example.xml | 23 +++++++++---------- endpoints/stats-response.xsd | 33 ++++++++++++++-------------- endpoints/stats.md | 33 +++++----------------------- manifest-entry.xsd | 7 ++++++ 4 files changed, 39 insertions(+), 57 deletions(-) diff --git a/endpoints/stats-response-example.xml b/endpoints/stats-response-example.xml index 8f8f884..c8ec54d 100644 --- a/endpoints/stats-response-example.xml +++ b/endpoints/stats-response-example.xml @@ -1,19 +1,16 @@ - - 0 - - 0 - 0 - 0 - 2022-07-10T09:00:00 + 2022-07-10Z + 397 + 0 + 106 + 204 diff --git a/endpoints/stats-response.xsd b/endpoints/stats-response.xsd index 2b32551..532d320 100644 --- a/endpoints/stats-response.xsd +++ b/endpoints/stats-response.xsd @@ -1,12 +1,11 @@ - @@ -21,11 +20,18 @@ This describes the format of the response returned by the `stats` endpoint of - EWP Interinstitutional Agreements API + EWP Interinstitutional Agreements API. + + + + The date at which these statistics were calculated. + + + @@ -33,7 +39,7 @@ - + Number of IIAs created in the local system which have been approved by the partner HEI, @@ -41,7 +47,7 @@ - + Number of IIAs created in the local system which have not been approved by the partner HEI, @@ -49,18 +55,11 @@ - + Number of IIAs created in the local system which have been approved by the partner HEI - and the matching copies of the partner have been approved by the local HEI - - - - - - - The exact time at which these statistics were calculated. + and the matching copies of the partner have been approved by the local HEI. diff --git a/endpoints/stats.md b/endpoints/stats.md index d383fad..8aceaf4 100644 --- a/endpoints/stats.md +++ b/endpoints/stats.md @@ -13,42 +13,20 @@ This endpoint allows the client to get the statistics describing IIAs from a spe Request method -------------- - * Requests MUST be made with either HTTP GET or HTTP POST method. Servers MUST - support both these methods. Servers SHOULD reject all other request methods. + * Requests MUST be made with HTTP GET method. -Request parameters ------------------- - -Parameters MUST be provided either in a query string (for GET requests), or in -the `application/x-www-form-urlencoded` format (for POST requests). - - -### `hei_id` (required) - -Identifier of the HEI to gather IIAs statistics from. -Response time ------------ - -Server SHOULD respond as fast as possible. This is why it is recommended to calculate statistics offline, rather than on request. -If the statistics are calculated offline, server MUST refresh them at least once a month. -It's also a reason why calculation date is included in the response. - - -Permissions ------------ +Other requirements +------------------ -Server SHOULD make this endpoint public. Server MUST allow EWP-Stats portal node to access this endpoint (TODO: to be verified) +Refer to [this document][ewp-architecture] for more details about requirements for statistics endpoint (TODO: update link for specific section after merging) -Handling of invalid parameters +Error handling ------------------------------ * General [error handling rules][error-handling] apply. - * Invalid `hei_id` values (i.e. references to HEIs which are not covered by - this host) MUST result in a HTTP 400 error. - Response -------- @@ -62,3 +40,4 @@ further information. [iias-api]: https://github.com/erasmus-without-paper/ewp-specs-api-iias [echo]: https://github.com/erasmus-without-paper/ewp-specs-api-echo [error-handling]: https://github.com/erasmus-without-paper/ewp-specs-architecture#error-handling +[ewp-architecture]: https://github.com/erasmus-without-paper/ewp-specs-architecture \ No newline at end of file diff --git a/manifest-entry.xsd b/manifest-entry.xsd index 755943b..fde909a 100644 --- a/manifest-entry.xsd +++ b/manifest-entry.xsd @@ -84,6 +84,13 @@ + + + + An URL at which the IIA `index` endpoint is being served. + + + From 787daa86bd9292e42af0bcca4b92881899e106b4 Mon Sep 17 00:00:00 2001 From: MBala98 Date: Fri, 26 Aug 2022 11:48:07 +0200 Subject: [PATCH 3/6] Add change log for version 6.2.0 --- CHANGELOG.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index fbb9062..5c67001 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,15 @@ Release notes This document describes all the changes made to the *Interinstitutional Agreements API* document, starting from its first beta draft version. +6.2.0 +----- + +* Add IIAs statistics endpoint URL to manifest +* Add IIAs statistics endpoint response schema +* Add IIAs statistics endpoint response example +* Add IIAs statistics endpoint README + + 6.1.0 ----- From 61779b4ddbca4d2dc37f5a605ebb92944672d300 Mon Sep 17 00:00:00 2001 From: MBala98 Date: Fri, 26 Aug 2022 23:33:35 +0200 Subject: [PATCH 4/6] Shortened change log for 6.2.0. Fixed manifest stats url --- CHANGELOG.md | 5 +---- endpoints/stats.md | 3 +-- manifest-entry.xsd | 2 +- 3 files changed, 3 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c67001..a003eba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,10 +7,7 @@ Agreements API* document, starting from its first beta draft version. 6.2.0 ----- -* Add IIAs statistics endpoint URL to manifest -* Add IIAs statistics endpoint response schema -* Add IIAs statistics endpoint response example -* Add IIAs statistics endpoint README +* Add IIAs statistics endpoint. 6.1.0 diff --git a/endpoints/stats.md b/endpoints/stats.md index 8aceaf4..27c5c7d 100644 --- a/endpoints/stats.md +++ b/endpoints/stats.md @@ -8,7 +8,7 @@ IIA Stats endpoint Summary ------- -This endpoint allows the client to get the statistics describing IIAs from a specific HEI. +This endpoint allows the client to get the statistics describing IIAs from a local HEI. Request method -------------- @@ -38,6 +38,5 @@ further information. [develhub]: http://developers.erasmuswithoutpaper.eu/ [statuses]: https://github.com/erasmus-without-paper/ewp-specs-management#statuses [iias-api]: https://github.com/erasmus-without-paper/ewp-specs-api-iias -[echo]: https://github.com/erasmus-without-paper/ewp-specs-api-echo [error-handling]: https://github.com/erasmus-without-paper/ewp-specs-architecture#error-handling [ewp-architecture]: https://github.com/erasmus-without-paper/ewp-specs-architecture \ No newline at end of file diff --git a/manifest-entry.xsd b/manifest-entry.xsd index fde909a..349c96c 100644 --- a/manifest-entry.xsd +++ b/manifest-entry.xsd @@ -87,7 +87,7 @@ - An URL at which the IIA `index` endpoint is being served. + An URL at which the IIA `stats` endpoint is being served. From 7d3bf3cd721a00648af68f6afa78335edb39f716 Mon Sep 17 00:00:00 2001 From: MBala98 Date: Sun, 4 Sep 2022 10:17:26 +0200 Subject: [PATCH 5/6] Delete calculation date --- endpoints/stats-response-example.xml | 1 - endpoints/stats-response.xsd | 7 ------- 2 files changed, 8 deletions(-) diff --git a/endpoints/stats-response-example.xml b/endpoints/stats-response-example.xml index c8ec54d..7b7c1bd 100644 --- a/endpoints/stats-response-example.xml +++ b/endpoints/stats-response-example.xml @@ -7,7 +7,6 @@ " > - 2022-07-10Z 397 0 106 diff --git a/endpoints/stats-response.xsd b/endpoints/stats-response.xsd index 532d320..0da7634 100644 --- a/endpoints/stats-response.xsd +++ b/endpoints/stats-response.xsd @@ -25,13 +25,6 @@ - - - - The date at which these statistics were calculated. - - - From 04d4d419d201505d0dd1c54fd32d202145b9db5e Mon Sep 17 00:00:00 2001 From: MBala98 Date: Mon, 5 Sep 2022 20:33:00 +0200 Subject: [PATCH 6/6] Add reference to specs architecture --- endpoints/stats.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/endpoints/stats.md b/endpoints/stats.md index 27c5c7d..559c022 100644 --- a/endpoints/stats.md +++ b/endpoints/stats.md @@ -19,7 +19,7 @@ Request method Other requirements ------------------ -Refer to [this document][ewp-architecture] for more details about requirements for statistics endpoint (TODO: update link for specific section after merging) +Refer to [this document][ewp-architecture] for more details about requirements for statistics endpoint. Error handling @@ -39,4 +39,4 @@ further information. [statuses]: https://github.com/erasmus-without-paper/ewp-specs-management#statuses [iias-api]: https://github.com/erasmus-without-paper/ewp-specs-api-iias [error-handling]: https://github.com/erasmus-without-paper/ewp-specs-architecture#error-handling -[ewp-architecture]: https://github.com/erasmus-without-paper/ewp-specs-architecture \ No newline at end of file +[ewp-architecture]: https://github.com/erasmus-without-paper/ewp-specs-architecture#ewp-statistics \ No newline at end of file