Document EFA-specific options

[vkrause]

This is basically the KPublicTransport's options as a starting point, especially the response format option might need some generalization considering JSON responses have been mentioned before. One could also leave that to the client to auto-detect?

[derf]

Hmmm, then compact vs verbatim XML would be documented, but XML vs JSON wouldn't. Would that make sense?

I'm not familiar with the JSON variant, so I'll follow your judgement here. If XML/JSON (and, perhaps, JSON variant) is trivial to auto-detect, leaving it out sounds sensible, otherwise I'm in favor of explicitly documenting both. Do you know whether there are EFA endpoints supporting both XML and JSON queries?

[vkrause]

I haven't worked with JSON EFA responses either before, but they do seem to be just one option away:

• XML: https://efa.vgn.de/vgn/XML_STOPFINDER_REQUEST?outputFormat=XML&coordOutputFormat=WGS84[DD.ddddd]&language=de&locationServerActive=1&type_sf=stop&name_sf=N%C3%BCrnberg%20Hauptbahnhof&anyObjFilter_sf=2&anyMaxSizeHitList=1
• JSON: https://efa.vgn.de/vgn/XML_STOPFINDER_REQUEST?outputFormat=JSON&coordOutputFormat=WGS84[DD.ddddd]&language=de&locationServerActive=1&type_sf=stop&name_sf=N%C3%BCrnberg%20Hauptbahnhof&anyObjFilter_sf=2&anyMaxSizeHitList=1

So, this is apparently something the client can control. Not all endpoints support this though:

• (compact) XML: https://mobile.defas-fgi.de/beg/XML_STOPFINDER_REQUEST?outputFormat=XML&coordOutputFormat=WGS84[DD.ddddd]&language=de&locationServerActive=1&type_sf=stop&name_sf=N%C3%BCrnberg%20Hauptbahnhof&anyObjFilter_sf=2&anyMaxSizeHitList=1
• JSON: https://mobile.defas-fgi.de/beg/XML_STOPFINDER_REQUEST?outputFormat=JSON&coordOutputFormat=WGS84[DD.ddddd]&language=de&locationServerActive=1&type_sf=stop&name_sf=N%C3%BCrnberg%20Hauptbahnhof&anyObjFilter_sf=2&anyMaxSizeHitList=1

How about two options to cover this:

• supportedOutputFormats: an array of strings containing valid arguments to the outputFormat parameter of an EFA query (XML and/or JSON).
• xmlOutputFormat: a string specifying the XML output format variant, either full or compact.

This gives us room for more variants, and allows for documenting different JSON formats too, in case those exist.

[derf]

:+1: looks good to me.

supportedOutputFormats = ["XML", "JSON"] deviates from the way we specify endpoint types (where we settled for type.efa = true instead of a list of literals), but I think that's alright. After all, we're specifying verbatim API request arguments here (and there's no guarantee that they will continue to be valid JSON keys).