This document describes the Institutions API. Once implemented by the host, it allows external clients to retrieve general information on institutions either covered, or otherwise known, by this host. This information includes things like address, logo image and key contact persons.
Initially, this API was supposed to work only with hei_ids covered by
the server's EWP Host. In other words, implementers were required to return
information only on "their own" HEIs. Later, however, it turned
out that
in some cases, it would also be very useful if the server could provide some
(very basic) information on other known HEIs too.
Therefore, it is now RECOMMENDED for server implementers to also provide some basic information on all external institutions which they refer to (by their SCHAC IDs) in other EWP APIs. It doesn't have to be much information though (most often, just the name will be enough).
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.
Clients are advised to use POST when passing large number of parameters (servers MAY set a limit on their GET query string length).
Parameters MUST be provided in the regular application/x-www-form-urlencoded
format.
hei_id (repeatable, required)A list of institution identifiers (no more than <max-hei-ids> items) - IDs of
HEIs the client wants to retrieve information on.
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 <max-hei-ids> via their
manifest entry (see manifest-entry.xsd). Clients SHOULD
parse this value (or assume its equal to 1).
Clients may retrieve proper HEI identifiers from other EWP APIs (most often, the Registry Service). Servers MUST be able to accept all HEI IDs declared in their manifest files, and all HEI IDs which they refer to in other EWP APIs.
This version of this API uses standard EWP Authentication and Security, Version 2. Server implementers choose which security methods they support by declaring them in their Manifest API entry.
This API provides data which is also usually accessible to the anonymous public by other channels. It is RECOMMENDED for server implementers to not be overly strict on security methods they require (i.e. it is RECOMMENDED to not require extra layers of encryption in requests and responses - TLS seems more than enough). Server implementers MAY also consider allowing this API to be accessed by anonymous clients.
General error handling rules apply.
Invalid (unknown) hei_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 hei_id values. If all values
are unknown, servers MUST respond with an empty <response> element.
This requirement is true even when <max-hei-ids> is equal to 1.
If the length of hei_id list is greater than <max-hei-ids>, servers
MUST respond with HTTP 400.
Servers MUST respond with a valid XML document described by the response.xsd schema. See the schema annotations for further information.