Concept of BASE URL should be clarified

[abollini]

In the introduction we use the term baseURL to refer both to the repository entry page (home page) than to the repository server origin.

Despite to be a bad practice some repositories are published under a path of the university domain, in this case I would like to make clear that

• it should be avoided, better to give a proper domain to the repository ;)
• the repository entry page would be something like https://myuniversity.edu/repository/home
• the .well-known api-catalog will be at https://myuniversity.edu/.well-known/api-catalog

Moreover, also for the ideal scenario where the repository is deployed in its own domain, let's say https://repository.myuniversity.edu

• the repository entry page will be something like https://repository.myuniversity.edu/home . The link should be exposed on the canonical URL of the repository home page if the https://repository.myuniversity.edu/ would resolve to a redirection
• the api-catalog will be at https://repository.myuniversity.edu/.well-known/api-catalog

[hvdsomp]

I think we will need a section on this because it’s come up before and it seems the current approach isn’t satisfactory yet.

[hvdsomp]

Thanks a lot for this feedback, @abollini . I have removed baseURL and introduced root-URL and (I hope) I made the concept clear by using your examples. Please have a look. @huberrob, it would be good to also check this change. Honestly, the wording in the previous version was not correct as per the Well-known URI RFC.

[huberrob]

I agree that having api-catalog at root-URL is useful, however repository managers sometimes do not have access to root-URL and I would therefore recommend to keep the baseURL in addition to the root-URL. Then api-catalog lookup should follow the sequence: first check root-URL if it is not there check baseURL

[hvdsomp]

Yes, that’s the problem with the well-known URI approach. One needs root access. But the well-known URI RFC is very clear about it all and, hence, we really need to stick to the root-URL approach. For repositories that don’t have access there, the api-catalog link at landing pages can be used. I can add language to make that more clear.

[hvdsomp]

@abollini Can you please have a quick look at the draft spec to see whether your issue is adequately addressed? The sections to check are https://signposting.org/API-Catalog/#discovery and https://signposting.org/API-Catalog/#discwellknown. Feel free to close the issue if all is good now.

[abollini]

@hvdsomp I would suggest to have the link to the api-catalog NOT at the root-URL but at the repository landing page, that would be one likes https://myuniversity.edu/repository/home or https://repository.myuniversity.edu/home, that I would name, repository landing page, according to the current samples. IMHO we are required to use the root-URL for the .well-known specification but not for the singposting api-catalog spec so in 2.3.2. api-catalog link at the root-URL I would refer to the repository landing page instead than to the root-URL Eventually, the image must be updated accordingly

[hvdsomp]

@abollini Please check the well-known URI RFC, one can just not do the /home thing. I'm sorry but we really need to follow that spec.

[abollini]

Hi @hvdsomp I could be wrong but I don't see mention of the link header in the .well-known RFC. It mandates the URI for the well-known stuff but not from which page(s) we should advertise it. To clarify, I'm suggesting to have https://repository.myuniversity.edu/.well-known/ and to expose a Link header at https://repository.myuniversity.edu/home to the previous URL

[hvdsomp]

Hey @abollini You can add typed links wherever you want. You’re encouraged! You just can’t decide what is a well-known URI. That’s been decided in the well-known URI RFC.

[hvdsomp]

To clarify, the first URL you list qualifies to be used as well-known URI; it just needs api-catalog appended to it. The second URL does not qualify. But, it can, as you suggest, have a link with api-catalog link relation that points at the former. The well-known URI RFC does not talk about typed links. The api-catalog Internet Draft does.

This is from the well-known URI RFC:

Well-known URIs are rooted in the top of the path's hierarchy; they are not well-known by definition in other parts of the path. For example, "/.well-known/example" is a well-known URI, whereas "/foo/.well-known/example" is not.

I think this issue has been discussed thoroughly and I suggest it can be closed. @abollini do you agree?

[abollini]

hi @hvdsomp yes, the updated image reflect a bit better my suggestion. I still think that we should remove the requirement for the ROOT-URL to link to the API catalog. The reason why I'm stressing this point is because if the ROOT-URL doesn't match with the Landing page URL it is highly likely that the webserver at the ROOT API domain is managed by a different team than the one that run the repository. While it is possible to convince the guy at the ROOT domain to manage the well-known folder as it must be done there by a general specification the requirement for the link header will come from a "domain specific" specification.

To be also more concrete, thinking to implement this specification in DSpace out-of-box the requirement about the well-known folder and the ROOT link header will be translated in instruction that must be manually followed by the installer, the requirement about the landing page can be "hardcoded" in the codebase so nothing special will be required by who perform the installation. I suspect that with a such approach lot of DSpace installations would miss to comply with the requirement at the ROOT URL mostly for the link header part. So my question is, do we really need to enforce also the link header from the ROOT?

[hvdsomp]

This is what the API Catalog Internet Draft says about the /.well-known/api-catalog URL:

A Web host (example.com) supporting this URI:

• SHALL resolve an HTTP(S) GET request to /.well-known/api-catalog and return an API catalog document.
• SHOULD resolve an HTTP(S) HEAD request to /.well-known/api-catalog with a response including a Link header with the relation(s) defined in Section 4

There's a SHOULD regarding the api-catalog link, which is also reflected in the FAIRiCat spec. There's no MUST, so implementations that don't/can't do it are still OK.

IMO, the solution is not to remove the api-catalog link from the root-URL in the picture because it reflects what the API Catalog spec states. A solution could be to add to the image and text to accomodate what you want to achieve, i.e. link to the FAIRiCat from a URL other than the root-URL and the object landing page URLs (already shown in image and described in spec). The question then becomes what the name of that URL is? Is it the repository entry page URL?

[hvdsomp]

I thought some more about this and propose to restructure the Discovery section as follows:

2.3. Discovery

Approaches under 2.3.1 and 2.3.2 may be combined; one approach must be supported.

2.3.1. Discovery via the root-URL: HTTP GET onroot-URL/.well-known/api-catalog` must yield FAIRiCat if the well-known URI is supported

2.3.2. Discovery via api-catalog links

• From the root-URL: HTTP HEAD on root-URL/.well-known/api-catalog should yield api-catalog link to FAIRiCat if the well-known URI is supported
• From the repository-entry-URL: HTTP HEAD/GET on repository-entry-URL may yield api-catalog link to FAIRiCat
• From object landing page URLs: HTTP HEAD/GET on object-landing-page-URL may yield api-catalog link to FAIRiCat

Sections 2.3.1 and 2.3.2 can have their own image.

@abollini would that approach address what you want to achieve?

[hvdsomp]

@abollini , all: I created a test version of the spec in which I implemented the above Discovery proposal. I would very much appreciate (prompt) feedback. From my perspective, it works, is correct vis-a-vis the API Catalog I-D, and opens the door for various repository situations. Check out the Discovery section of the test version.

[abollini]

thanks @hvdsomp the new version makes things clearer imho. I'm happy with this formulation

[hvdsomp]

FYI: The new version of the API-Catalog spec offers more flexibility with regard the location of the well-know URI by saying:

SHOULD host the /.well-known/api-catalog URI at a predictable location.

It also provides examples of that not being at the root URL. So, it will be possible to simplify the language in FAIRiCat with that regard.

This new version also recommends Link Sets as serialization format for API Catalogs.

[hvdsomp]

New version of FAIRiCat spec with much simplified Discovery section, as a result of added flexibility regarding location of /.well-known/api-catalog in the new version of the API-Catalog spec

@abollini it would be good if you could have a look

[abollini]

Hi @hvdsomp sorry to have missed this follow-up. The new version looks great to me. Should we remove the slash in the text and the image when we refer to <repository-entry-URL/>?

[hvdsomp]

Thanks @abollini . I made the suggested changes and am closing the issue as resolved.