Allow use of relative URLs for queries in yaml specification files

[jaw111]

When using an yaml specification file to generate an API, it appears the queries must be referenced by absolute URLs. This does not make the specifications very portable e.g. if I want to deploy (different versions of) a specification in different environments, I need to change those URLs per environment.

It would be a nice improvement if the query URLs were resolved relative to the URL of the yaml specification file.

[c-martinez]

Hi @jaw111 -- could you explain your use case a little bit further? Without knowing what you are trying to achieve, I am not sure the yaml specification will work for your. The yaml specification files builds an API from queries which are available on the web. Those queries are findable via their URLs, but it was not designed with the idea of those URLs being dynamic.

My way of viewing the problem is as follows:

• The same specification file using different URL's depending on the environment will generate different API's.
• The same specification file using different URL's gives the specification flexibility.
• The same specification file generating different API's means the specification file could have inconsistent behaviours.

I see it as a trade-off between flexibility and consistency. And while flexibility is always nice to have, I think from the point of view of reproducibility, consistency should take priority.

That is my point of view, but I would like to hear your thoughts.

[jaw111]

I want to reference to the sparql files that are in the same folder on the webserver as the yaml file by using a relative rather than fully qualified url. That makes it far easier to move those files to another folder, or indeed another web host, without needing to modify the yaml. Nothing is dynamic, only grlc needs to resolve such urls relative to the url of the yaml specification. Seems pretty much standard webby behavior to me. Sent from my Samsung Galaxy smartphone.

…

-------- Original message -------- From: Carlos Martinez ***@***.***> Date: 18/05/2021 08:46 (GMT+01:00) To: CLARIAH/grlc ***@***.***> Cc: John Walker ***@***.***>, Mention ***@***.***> Subject: Re: [CLARIAH/grlc] Allow use of relative URLs for queries in yaml specification files (#331) Hi @jaw111<https://github.com/jaw111> -- could you explain your use case a little bit further? Without knowing what you are trying to achieve, I am not sure the yaml specification will work for your. The yaml specification files builds an API from queries which are available on the web. Those queries are findable via their URLs, but it was not designed with the idea of those URLs being dynamic. My way of viewing the problem is as follows: * The same specification file using different URL's depending on the environment will generate different API's. * The same specification file using different URL's gives the specification flexibility. * The same specification file generating different API's means the specification file could have inconsistent behaviours. I see it as a trade-off between flexibility and consistency. And while flexibility is always nice to have, I think from the point of view of reproducibility, consistency should take priority. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub<#331 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AAS5B7KMXIC3JEYG7L334ATTOIEMZANCNFSM42QQ6HSQ>.

[c-martinez]

My main worry is that it could become ambiguous which query is behind a specific API endpoint. But after actually I don't think that would be the case. I think it would work as follows:

For a spec file such as:

title: TestAPI
queries:
  - http://otherserver/remote-query.rq
  - ./local-query.rq

Spec file could be available at http://myserver/repo/url.yml and a query on the same folder http://myserver/repo/local-query.rq

This would generate the following API:

Resource	URL
Swagger UI	http://grlc.io/api-url?specUrl=http://myserver/repo/url.yml
Query 1	http://grlc.io/api-url/local-query?&specUrl=http://myserver/repo/url.yml
Query 2	http://grlc.io/api-url/remote-query?&specUrl=http://myserver/repo/url.yml

If we move the spec file to a different folder in the same server (or even to a different server)

Spec file could be available at http://myserver/other-repo/url.yml and the query on the same folder http://myserver/other-repo/local-query.rq

This would generate the following API:

Resource	URL
Swagger UI	http://grlc.io/api-url?specUrl=http://myserver/other-repo/url.yml
Query 1	http://grlc.io/api-url/local-query?&specUrl=http://myserver/other-repo/url.yml
Query 2	http://grlc.io/api-url/remote-query?&specUrl=http://myserver/other-repo/url.yml

From the query URL, it is always possible to trace back which query is behind that endpoint. @jaw111, does this cover your expected functionality? Do you see any gaps in what I'm proposing?

[jaw111]

Seems ok to me. The only small concern I'd have is that the name of the end point is derived from the URL of the query, being the last segment of the path minus any filename extension. Is there any risk to have clashes? Actually that's independent of this proposed change as it can also happen if queries are referenced using absolute URLs too. Any idea what would happen in such a case? Sent from my Samsung Galaxy smartphone.

…

-------- Original message -------- From: Carlos Martinez ***@***.***> Date: 28/05/2021 08:56 (GMT+01:00) To: CLARIAH/grlc ***@***.***> Cc: John Walker ***@***.***>, Mention ***@***.***> Subject: Re: [CLARIAH/grlc] Allow use of relative URLs for queries in yaml specification files (#331) My main worry is that it could become ambiguous which query is behind a specific API endpoint. But after actually I don't think that would be the case. I think it would work as follows: For a spec file such as: title: TestAPI queries: - http://otherserver/remote-query.rq - ./local-query.rq Spec file could be available at http://myserver/repo/url.yml and a query on the same folder http://myserver/repo/local-query.rq This would generate the following API: Resource URL Swagger UI http://grlc.io/api-url?specUrl=http://myserver/repo/url.yml Query 1 http://grlc.io/api-url/local-query?&specUrl=http://myserver/repo/url.yml Query 2 http://grlc.io/api-url/remote-query?&specUrl=http://myserver/repo/url.yml If we move the spec file to a different folder in the same server (or even to a different server) Spec file could be available at http://myserver/other-repo/url.yml and the query on the same folder http://myserver/other-repo/local-query.rq This would generate the following API: Resource URL Swagger UI http://grlc.io/api-url?specUrl=http://myserver/other-repo/url.yml Query 1 http://grlc.io/api-url/local-query?&specUrl=http://myserver/other-repo/url.yml Query 2 http://grlc.io/api-url/remote-query?&specUrl=http://myserver/other-repo/url.yml From the query URL, it is always possible to trace back which query is behind that endpoint. @jaw111<https://github.com/jaw111>, does this cover your expected functionality? Do you see any gaps in what I'm proposing? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub<#331 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AAS5B7MT4UF2EC5NRUC5VJLTP45CJANCNFSM42QQ6HSQ>.

[c-martinez]

Ok, created a PR implementing this.

Yes, there might be clashes on the names of the endpoints. Without looking into it, I think only the last endpoint in the specification (with the conflicting name) will be created. But indeed this will happen even with absolute URLs, so perhaps should be a separate issue.