search

erasmus-without-paper / ewp-specs-api-institutions

Specifications of EWP's Institutions API.
MIT License
0 stars 0 forks source link

Embedded-mobility-factsheet DRAFT #7

Closed wrygiel closed 7 years ago

wrygiel commented 7 years ago

Draft proposal of how to allow embedding mobility factsheets into the Institutions API response.

(At the moment, I am somewhat against including this, because I think no one will actually implement it.)

wrygiel commented 7 years ago

Related discussion:

https://github.com/erasmus-without-paper/ewp-specs-api-institutions/issues/5#issuecomment-257543246

kaiqu commented 7 years ago

Draft proposal of how to allow embedding mobility factsheets into the Institutions API response. (At the moment, I am somewhat against including this, because I think no one will actually implement it.)

The proposal has two aspects: 1) Titles/headers in addition to content 2) Nestability

I definitely vote for 1) - both for classification/link display purposes and for aligning with the model. Since I have seen examples of nested fact sheets, I vote for 2) as well, but not as strongly.

wrygiel commented 7 years ago

BTW, do you (Norway) plan to implement this? I am quite sure we (Poland) won't. We will rather stick with PDF fact sheets, at least in the beginning.

kaiqu commented 7 years ago

BTW, do you (Norway) plan to implement this? I am quite sure we (Poland) won't. We will rather stick with PDF fact sheets, at least in the beginning.

Whether we will implement nested fact sheets, I don't know, but I assume we will supply a title/header of some sort. Anyway, since both the header and the actual nesting is optional, I don't see the harm of implementing it: The partners who won't implement one and/or the other can simply leave that information out as server and ignore ("flatten") incoming complexity as client?

wrygiel commented 7 years ago

What I meant was - do you have this kind of data in your database? Because we don't. I wonder if any partner does.

kaiqu commented 7 years ago

What I meant was - do you have this kind of data in your database? Because we don't. I wonder if any partner does.

As far as I can see, we don't have recursive fact sheet information, but we do have headers (information types). If the existing nested fact sheets aren't based on databases, they are presumably file based. If those HEIs want to keep the nested structure in EWP, they will presumably change their databases to accommodate this.

I think the relevant question is whether any of the HEIs want to a) start or b) continue to serve nested fact sheets in EWP. If a), they will have to change their database structure in this respect.

wrygiel commented 7 years ago

If those HEIs want to keep the nested structure in EWP, they will presumably change their databases to accommodate this.

No, wait... How to explain this...

The purpose of introducing nesting was only to help developers "display" their flat data in a locally predefined header structure. This means that I don't expect any partner to have nesting in their databases, and surely I don't expect anyone to accommodate their databases. I only expect that what they do have should not necessarily always be presented as a flat list of headers. I want them to have control over how this gets displayed.

One way of giving this control would be to allow them to pass raw HTML. But this would introduce security issues (XSS, etc.). Hence this format proposal. It's not HTML, but it allows to group plaintext content in - kind of - <h1>..<hN> headers, thus allowing developers to describe how their data should be displayed.

But still, I believe that PDF is much better and much simpler solution. I think this proposal should be dropped. I don't see any reason for passing raw text content of this kind...

kaiqu commented 7 years ago

I believe that PDF is much better and much simpler solution. I think this proposal should be dropped. I don't see any reason for passing raw text content...

Ok, that's fine by me. But I assume having a header is still a good idea, for link display?

janinamincer-daszkiewicz commented 7 years ago

I prefer to read text straight from the page, not PDF.

wrygiel commented 7 years ago

But I assume having a header is still a good idea, for link display?

What do you mean exactly?

I prefer to read text straight from the page, not PDF.

Everyone does. Problem is, HTML pages may contain many attack vectors (XSS, CSRF, etc.). It's much safer to redirect the user to read the fact sheets directly on the target institution's servers. And we already allow for it (see here).

kaiqu commented 7 years ago

But I assume having a header is still a good idea, for link display?

What do you mean exactly?

I was thinking about a logical header like "Visa contacts" or "Course catalogue" describing the contents. If the information was to be displayed inline, the header would typically be displayed as a HTML header.

Now that we're leaning towards a link to a PDF, I was thinking it could be used as a logical display of the link (as in "see here" link above, where "here" is a logical display of the link) - but then I guess it's customary to include the logical display in the link itself, so forget about that part. (Remember, as a database developer I'm not well versed in markup languages)

The question is whether it's still useful with some header info to classify the contents of a (PDF) link? (The header is optional in the model, so it would only be used if/when the server had something meaningful to put there)

In the model, the HEI Information entity is not just used for links, but also for inline content:

From your earlier comments, I take it that the former is unsafe and should be dropped. Is that the case for the latter as well? It seems very cumbersome to have to click a PDF link just to see some contact information, but maybe it's necessary for security purposes?

kaiqu commented 7 years ago

@wrygiel, I need an answer to this, to finalize the model and dictionary:

In the model, the HEI Information entity is not just used for links, but also for inline content:

  • Free-form Content or
  • Contact info like Email/Phone/Fax/Address

I.e. fact sheet information.

From your earlier comments, I take it that the former is unsafe and should be dropped. Is that the case for the latter as well? It seems very cumbersome to have to click a PDF link just to see some contact information, but maybe it's necessary for security purposes?

wrygiel commented 7 years ago

Now that we're leaning towards a link to a PDF, I was thinking it could be used as a logical display of the link (as in "see here" link above, where "here" is a logical display of the link)

Ok, so you meant having an ability to provide a list (or even a tree) of links with labels, right?

This information might indeed be useful for the client. But I'm not sure if any servers would provide it (because of the additional workload of having it updated later on). I would rather guess they would prefer providing a single PDF (or a single webpage) which someone if already keeping up-to-date. I suggest not to add it just now, to avoid clutter.

From your earlier comments, I take it that [Free-form Content] is unsafe and should be dropped

In particular:

Hence my conclusion that passing free-form content might be unsafe. It's doable all right, but someone might try to exploit it in the future.

@wrygiel, I need an answer to this, to finalize the model and dictionary

I don't think you will be able to really "finalize" the model just know. It will probably keep mutating in the next months. However, in this first version, I suggest we drop the free-form content. We might add it back later, if partners judge it's necessary.

kaiqu commented 7 years ago

Ok, so you meant having an ability to provide a list (or even a tree) of links with labels, right? This information might indeed be useful for the client. But I'm not sure if any servers would provide it (because of the additional workload of having it updated later on). I would rather guess they would prefer providing a single PDF (or a single webpage) which someone if already keeping up-to-date. I suggest not to add it just now, to avoid clutter.

Ok.

  • It's difficult to store/deliver free-form content without some kind of rich-formatting.
  • There's no other well-known format for rich-formatting besides HTML.
  • Displaying foreign HTML is unsafe (without proper protection).

Hence my conclusion that passing free-form content might be unsafe. It's doable all right, but someone might try to exploit it in the future.

Ok.

@wrygiel, I need an answer to this, to finalize the model and dictionary

I don't think you will be able to really "finalize" the model just know. It will probably keep mutating in the next months.

I know :-) I meant "finalizing" enough for Publishing a new version.

However, in this first version, I suggest we drop the free-form content. We might add it back later, if partners judge it's necessary.

No problem.