Add support for TRIAS Endpoints

[1Maxnet1]

This Pull Request introduces a draft for the required properties for trias clients and how to specify them. The information was collected from the existing list available in trias-client. I already found some issues, I would like to discuss:

• Some Endpoints offer test-endpoints, which are usually the same as the production endpoint but at least in one case they also differ in Authorization (see the SBB). So what I iagined would be to use a boolean that indicate, whether this is a productive or test endpoint instead of offering the test-URL. This would lead to a lot of endpoints be defined two times, with only a different URL, but would allow to specify test-endpoints as that differ in more then the base URL.
• I wasn't sure how to define access: In the mentioned documentation sometimes a contract is required, but independent from whether a registration is required or not. Currently this is implicitly defined, if you need an authorization you usually need an registration as well. Except for the SBB testpoint, where you need an authorization with an publicly available key.
• A link to the documentation of the endpoint (and for registration) would be useful for developers. However this repo states to be "machine-readable" and in the other definitions, it is also not available. So should we add it or not?

Every kind of feedback is appreciated.

[derhuerst]

Thanks for your contribution!

My personal opinions on your points:

• Some Endpoints offer test-endpoints, which are usually the same as the production endpoint but at least in one case they also differ in Authorization (see the SBB). So what I iagined would be to use a boolean that indicate, whether this is a productive or test endpoint instead of offering the test-URL. This would lead to a lot of endpoints be defined two times, with only a different URL, but would allow to specify test-endpoints as that differ in more then the base URL.

I'm also in favour of having test endpoints as separate entries with e.g isTestingEndpoint: true.

• I wasn't sure how to define access: In the mentioned documentation sometimes a contract is required, but independent from whether a registration is required or not. Currently this is implicitly defined, if you need an authorization you usually need an registration as well. Except for the SBB testpoint, where you need an authorization with an publicly available key.

I propose to keep technical means of authentication/authorization (e.g. keys) in a different field than legal/organizational means of authorization, mainly because the former is a clear cut, whereas the latter is a "fuzzy" topic.

• A link to the documentation of the endpoint (and for registration) would be useful for developers. However this repo states to be "machine-readable" and in the other definitions, it is also not available. So should we add it or not?

I think having a link to a documentation page (or even multiple) is very helpful!

With this collection being machine-readable, we have the advantage of being able to filter or transform it into multiple representations (e.g. an HTML page equivalent, or reference is in code like kpublictransport & hafas-client do it); That does not mean that information intended for humans isn't helpful in here!

[vkrause]

Thank you! This should also work as-is for OJP endpoints I think.

• Some Endpoints offer test-endpoints, which are usually the same as the production endpoint but at least in one case they also differ in Authorization (see the SBB). So what I iagined would be to use a boolean that indicate, whether this is a productive or test endpoint instead of offering the test-URL. This would lead to a lot of endpoints be defined two times, with only a different URL, but would allow to specify test-endpoints as that differ in more then the base URL.

Including test endpoints in some form definitely makes sense, we also have that use-case for other protocols. Doing this as separate files is probably necessary though, due to differences in other properties like authentication, or e.g. Motis, which only has a testing endpoint so far.

• I wasn't sure how to define access: In the mentioned documentation sometimes a contract is required, but independent from whether a registration is required or not. Currently this is implicitly defined, if you need an authorization you usually need an registration as well. Except for the SBB testpoint, where you need an authorization with an publicly available key.

• A link to the documentation of the endpoint (and for registration) would be useful for developers. However this repo states to be "machine-readable" and in the other definitions, it is also not available. So should we add it or not?

"machine-readable" hits its limits once human interaction is required anyway, like for registering or negotiating access. Collecting that information here definitely makes sense, but it doesn't need to be machine readable IMHO.

How to best collect such service-specific notes came up before, one possibility would be to put that into a .md file alongside the JSON data for example.

[1Maxnet1]

How to best collect such service-specific notes came up before, one possibility would be to put that into a .md file alongside the JSON data for example.

I would be fine with a .md file as well. What I came up with would be a property like registrationURL or sth. similar. How is this done for the hafas endpoints currently ? Is there any further information collected additionally to the attribution information? If not I would keep it that way for trias and would add a link to the site in attritbution:{homepage: ...}

[derhuerst]

I would be fine with a .md file as well. What I came up with would be a property like registrationURL or sth. similar. How is this done for the hafas endpoints currently ?

The HAFAS endpoints that are in this repo right now don't require registration.

[1Maxnet1]

So I reworked it including your feedback and created a TRIAS-Providers.md, with an example entry. I thought adding the URL into the json wouldn't make to much sense, as technically it is not required for a client to use it. Let me know if you have any further points :+1:

[1Maxnet1]

How do you handle commit history? In my opinion i could squash some of the commits together to keep the history cleaner. But I would be fine with leaving them as is as well. You can tell :D

[derhuerst]

How do you handle commit history? In my opinion i could squash some of the commits together to keep the history cleaner.

We haven't discussed this.

In my opinion, when a PR is ready for merging, it makes sense to clean up the commit history to commits as atomic and orthogonal as (reasonably) possible. 👍

[1Maxnet1]

In my opinion, when a PR is ready for merging, it makes sense to clean up the commit history to commits as atomic and orthogonal as (reasonably) possible. +1

I cleaned it up :+1: If there is anything you would like changed in the git history, just let me know. I also made a backup of the old one. Otherwise the PR looks good to me.

[1Maxnet1]

I just created a .json file for the bwegt/NVBW TRIAS-Endpoint and recognized, they use another authorization method (https://github.com/1Maxnet1/transport-apis/tree/nvbw-endpoint). Should I add this addition to this PR or add it in another PR together with the submitted bwegt-trias.json ?

[derhuerst]

I just created a .json file for the bwegt/NVBW TRIAS-Endpoint and recognized, they use another authorization method. Should I add this addition to this PR or add it in another PR together with the submitted bwegt-trias.json ?

What is different? Just https://github.com/1Maxnet1/transport-apis/commit/f5025fbabc3ee2bc499bb0016cf40789d0474ab2? Yeah, just add it here.

[1Maxnet1]

I just created a .json file for the bwegt/NVBW TRIAS-Endpoint and recognized, they use another authorization method. Should I add this addition to this PR or add it in another PR together with the submitted bwegt-trias.json ?

What is different? Just 1Maxnet1@f5025fb? Yeah, just add it here.

Yeah, just that, added it. Everything resolved now from my side