document OJP/TRIAS APIs

[derhuerst]

@andaryjo started doing this in the trias-client docs.
@vkrause's kpublictransport also has support for >1 TRIAS endpoint.

Let's define a way to specify all relevant aspects of TRIAS API endpoints in a machine-readable way, so that client libraries can use this information! This way, there will be

• less maintenance, as upstream changes to the individual endpoints will only have to be investigated once.
• better coverage of all existing API endpoints, as client libraries can easily pull the list of all known ones.

[vkrause]

Thanks for getting this started! Adding this here has also been somewhere on my todo list :)

We have only tested two endpoints so far, so not a lot of experience on how well things generalize yet:

• SBB (using OJP)
• VVO (using TRIAS)

OJP and TRIAS turned out to be 90+% the same code for us, so we are supporting both with the same implementation, but here we might still want to model them as different protocols I guess.

Besides the endpoint URL, the HTTP Content-Type header for requests seems to be a relevant parameter (or I just haven't found one yet that works universally).

I haven't looked into implementing multi-language support yet, so not sure if the options for that we have for other APIs are relevant.

[andaryjo]

Besides the endpoint URL, the HTTP Content-Type header for requests seems to be a relevant parameter (or I just haven't found one yet that works universally).

That's my experience as well. application/xml works for most providers, but one I know of explictly requires text/xml. I don't think the TRIAS specification states anything about the Content-Type. So this is something that would need to get included in the protocol-specific options.

[andaryjo]

Another thought: Most TRIAS APIs require authorization and the implementation is proprietary. Some providers use a RequestorRef XML tag, some use a header and some require you to include an API key / token in the URL path.

This will make it really hard for a TRIAS client to use these specifications as a basis for API connectvity, because it will likely require a custom implementation for every provider anyway.

[derhuerst]

This will make it really hard for a TRIAS client to use these specifications as a basis for API connectvity, because it will likely require a custom implementation for every provider anyway.

Would it? We could agree to add specific fields/values for each known auth type.

[1Maxnet1]

Another thought: Most TRIAS APIs require authorization and the implementation is proprietary. Some providers use a RequestorRef XML tag, some use a header and some require you to include an API key / token in the URL path.

This will make it really hard for a TRIAS client to use these specifications as a basis for API connectvity, because it will likely require a custom implementation for every provider anyway.

Additionally this could be something to report back to VDV so they could consider adding it to a updated TRIAS-verison for the future?

[1Maxnet1]

And is there already any current plan on how to continue on this issue? I already started to note down some endpoints, but would rather directly submit them to this repo. I could offer to create a draft in a fork of me, so we have something we can discuss, if no one started on this issue yet.

[derhuerst]

This will make it really hard for a TRIAS client to use these specifications as a basis for API connectvity, because it will likely require a custom implementation for every provider anyway.

Additionally this could be something to report back to VDV so they could consider adding it to a updated TRIAS-verison for the future?

Adding what specifically?

Personally, I'd like VDV to only use standard HTTP mechanisms, preferably the Authorization header, or at least something that can easily be specified with an OpenAPI spec.

[derhuerst]

And is there already any current plan on how to continue on this issue? […] I could offer to create a draft in a fork of me, so we have something we can discuss, if no one started on this issue yet.

Yes, create a draft in a fork, then submit a work-in-progress PR against this repo. We can then discuss the markup's details in there.

[1Maxnet1]

This will make it really hard for a TRIAS client to use these specifications as a basis for API connectvity, because it will likely require a custom implementation for every provider anyway.

Additionally this could be something to report back to VDV so they could consider adding it to a updated TRIAS-verison for the future?

Adding what specifically?

Personally, I'd like VDV to only use standard HTTP mechanisms, preferably the Authorization header, or at least something that can easily be specified with an OpenAPI spec.

Totally agree. What I meant, was that authorization or content-type could be added to be a part of the specification.

[derhuerst]

cc @sgrossberndt @WernerKohl

[1Maxnet1]

Merge Request #52 was just merged, forgot to mention it in this issue. I created another one #53 for a first json file.