Proposal and suggested improvements for institutions and ounits APIs

[sascoms]

REF: https://github.com/erasmus-without-paper/ewp-specs-api-institutions/blob/8132201b5f5ce3dbe99aecef53ec6c6e2f744885/response-example.xml#L89

We have the following proposal and improvements regarding institutions and ounits APIs:

1. institutions api should only have information about the HEI. And should not anymore list ounits.

2. organizational units list (currently contained in institutions API) should be a separate API. with a name like "ounits-index"

3. current ounits API should be renamed to something like ounits-get or ounits-details or ounits-info or similar to reflect its functionality. The content and functionality will remain same.

4. new ounits-index API should have a key=>label pair type format. The current implementation has only ids listed. And to fetch a HEIs ounits labels, you need to get first the ids from institutions API and then loop this list of ounits and fetch each (or group of) ounit details (!max allowed ids).

Sample response for onits-index API: `

5050444

 <code>fsat.no</id>
 <label lang="en">fsat.no</label>

`

or

`

5050444

 <label>fsat.no</label>

`

Drawbacks and disadvantages of the current APIs in use:

• IDs on their own are not useful and has no direct use.
• In order to display and let a user select an academic unit from a list, we need first to fetch all ids. And then call units API to get the name of the academic unit.
• This should be like the basic HTML combo/select box format: key->value pairs as a basic standard and minimum requirement for usability.
• Very much unnecessary HTTP traffic.
• In most of the use cases, the id/label pairs will be enough to use in IIAs or other EWP modules.

PS: The same problems and suggestions are valid for courses APIs, too. We will open the same issue under courses API, too.

[kamil-olszewski-uw]

Do you mean that after fetching the data via, for example, the IIAs API, you have to use the Institutions API afterwards to find out the names of the organizational units?

In our system, we keep the codes and names of partner organizational units in the HEIs dictionary. If any units are missing on our side, the user can download them.

[georgschermann]

we also faced similar issues when using these APIs (there are a few HEIs with several hundred ounits), my thought about it was to add the human-readable "values" directly to the ounit list in the institutions API, but a separate index/mapping endpoint would also be feasible I think. The big problem currently is, that you need to fetch the whole ounit data to know which ounit it is or what to show the user.

[umesh-qs]

@sascoms We do the same way as @kamil-olszewski-uw mentioned. Only advantage with the new API you are proposing is that you can the ounit list almost real time vs periodic refresh.

But this periodic refresh can also be solved if we have CNR as proposed in https://github.com/erasmus-without-paper/ewp-specs-api-factsheet/issues/2

[sascoms]

As a general reply:

The main problem is that the API does not have a direct functionality.

What we all mostly need is a key=>pair list to show to the user or to store it somewhere.

If the API was featuring a ID=>LABEL pair list, one HTTP request would be enough to fetch all the list. And you would need the details API only if you require more details about a unit.

And also the unnecessary traffic and requests number is another problem.

A HEI has 250 units. To create a simple html combo/select box,

• first fetch IDs from inst. API.
• loop those IDs (!max allowed ids) and fetch details of each unit.
• get the label from the fetched details
• compose the pairs and display the select box

Let's say max allowed ids = 10 1 request for inst. API + 25 requests for ounits details; total 26 HTTP requests.

Why?

This needs a more efficient way.

Caching is already necessary. Yes. But other than for performance, it has to be used as a "workaround" for this problem.

And yes, every problem in those API designs has a workaround. And we as developers can definitely find a way to turn around such design problems.

But why? Why not correcting the root design problem? We need to correct first the problematic design.

And a common note: The new, modern and popular products' APIs should really be examined in details before new versions of EWP APIs are published.

[umesh-qs]

@sascoms I agree that there is need to look at the root designs of APIs for better efficiency. But at the moment, there is a lot of stuff on the plate and we should only focus on changes that are must. Or at least find a less taxing solution. May be adding ounit label in institution API will serve the purpose.

[sascoms]

Right and I agree. But, at least there can be made a planning and roadmap. ie: "x, y, z, .. issues will be discussed in the meeting on x.y.z"

[janinamincer-daszkiewicz]

Eser, we do have a plan and a roadmap. Infrastructure Forum is just for that, to share this with the providers.