From cf915eba36c9c7350cb5f782df462ee9bc7570e8 Mon Sep 17 00:00:00 2001 From: Wojciech Rygielski Date: Fri, 10 Feb 2017 11:35:20 +0100 Subject: [PATCH] Allow retrieval by code https://github.com/erasmus-without-paper/general-issues/issues/21 --- README.md | 33 +++++++++++++++++++-------------- manifest-entry.xsd | 8 ++++++++ response.xsd | 5 ++--- 3 files changed, 29 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index fcc5ad7..70ceb1a 100644 --- a/README.md +++ b/README.md @@ -115,17 +115,19 @@ are conducted. This parameter MUST be required by the server even if the server covers only a single institution. -### `los_id` (repeatable, required) +### `los_id` or `los_code` (repeatable, required) -A list of LOS identifiers (no more than `` items) - IDs of LOSes -the client wants to retrieve information on. +A list of ID or codes of LOSes to return (no more than `` or +`` items, respectively). The requester MUST provide either a +list of `los_id` values, or a list of `los_code` values, **but not both**. This parameter is *repeatable*, so the request MAY contain multiple occurrences of it. The server is REQUIRED to process all of them. -Server implementers provide their own chosen value of `` via -their manifest entry (see [manifest-entry.xsd](manifest-entry.xsd)). Clients -SHOULD parse this value (or assume it's equal to `1`). +Server implementers provide their own chosen values of `` and +`` via their manifest entry (see [manifest-entry.xsd] +(manifest-entry.xsd)). Clients SHOULD parse these values (or assume they're +equal to `1`). ### `lois_before` (optional) @@ -191,14 +193,17 @@ Handling of invalid parameters * Invalid (or unknown) `hei_id` values MUST result in a HTTP 400 error response. - * Invalid (unknown) `los_id` values MUST be **ignored**. Servers MUST - return a valid (HTTP 200) XML response in such cases, but the response will - simply not contain the information on the unknown `los_id` values. If - all values are unknown, servers MUST respond with an empty `` - element. This requirement is true even when `` is `1`. - - * If the length of `los_id` list is greater than ``, - servers MUST respond with HTTP 400. + * Invalid (or unknown) `los_id` and `los_code` values MUST be **ignored**. + Servers MUST return a valid (HTTP 200) XML response in such cases, but the + response will simply not contain any information on these missing entities. + If all values are unknown, servers MUST respond with an empty `` + element. This requirement is true even when both `` and + ` are set to `1`. + + * If the length of `los_id` list is greater than `` (or the + length of `los_code` list is greater than ``), then the + server MUST respond with HTTP 400. Clients SHOULD split such large requests + into a couple of smaller ones. Response diff --git a/manifest-entry.xsd b/manifest-entry.xsd index 6e10a96..3f02c3f 100644 --- a/manifest-entry.xsd +++ b/manifest-entry.xsd @@ -58,6 +58,14 @@ + + + + The maximum number of `los_code` parameters the server is willing to accept + in one request. + + + diff --git a/response.xsd b/response.xsd index 8440935..031ce07 100644 --- a/response.xsd +++ b/response.xsd @@ -46,7 +46,7 @@ This represents a single result. Servers will produce one such element for - each of the `los_id` values passed in the Courses API call. + each of the `los_id` or `los_code` values passed in the Courses API call. This element describes a single Learning Opportunity entity, along with some possible references to its "child nodes". @@ -57,8 +57,7 @@ - Unique identifier of this LOS. Will always match one of the `los_id` values - passed in the Courses API call. It SHOULD NOT be displayed to the user (use + Unique identifier of this LOS. It SHOULD NOT be displayed to the user (use `los-code` for that). Read an introduction on LOS and LOI IDs here: