New Lift and Escalator API - initial thoughts
294 views
Skip to first unread message
Evelyn Snow
Jan 30, 2024, 4:06:43 PM1/30/24
to openrail...@googlegroups.com
Hi all,
I've finally had the chance to get to grips with the new Lift and Escalator API, I'll try to
summarise my observations. I'll start with the problems.
1. You need to email someone to sign up. Not the end of the world, but definitely higher
friction than many of the self-service APIs. The explanation for this (and other shortcomings)
appears to be that they intend to eventually offer it through the Rail Data Marketplace.
2. The initial information was extremely lacking. All you really had to go on were the two
documents you received if you were subscribed to the old API, which told you nothing about
endpoints or authentication. Peter had to go digging to work out the fundamentals, and I was
only informed of the URL for the public-facing API documentation earlier today.
The communication about the new API suggested that the documentation would be available via
Anypoint, with credentials available on request. When I requested it, I was told that it was
Network Rail internal only, but after some back-and-forth, was given - for the first time -
a link to the public documentation, a day before the old API is due to be closed down.
3. The mandatory protocol is extremely obtuse, it's effectively a requirement that you model
your interface around the interface of National Rail's access map, whether or not that's
appropriate. Some of its requirements are challenging - if not impossible - to comply with,
and some of the requirements are wrong; for example, you are obliged to say that the lifts
in Warwick Parkway, a station closer to Birmingham than London, are managed by TfL, or that
no live information is available in cases where this is untrue. I've expressed my concerns to
Network Rail, who say that the protocol may be revisited in future, with no commitment.
4. The contact at Network Rail who I was discussing this issue with requested that I edit
the article on the new API to remove the example API keys. I wasn't responsible for adding
these, but I mentioned briefly in my introduction that I was a contributor to the wiki. They
have acknowledged that the credentials are fictional, but nevertheless justified their request by
pointing to the first line in the terms and conditions:
"The credentials received are to be used solely by the person initiating the request unless
otherwise made clear during the request review process that the request is on the behalf of
another person or organization."
Since the credentials are entirely fictional, and generated randomly by Peter, not derived from
actual credentials, they are not "the credentials received".
To add insult to injury, the public documentation itself features example credentials. We've
changed the examples in the wiki to mirror those, I'm unsure yet whether this will be enough to
satisfy them.
I don't like feeling that I'm under pressure to make community documentation worse to accommodate
Network Rail's whims. They've bungled more than enough in their own communication/documentation
without insisting we join in.
My thanks to Peter for his guidance dealing with this.
Here's the diff:
https://wiki.openraildata.com/index.php?title=Stations_Experience_API&diff=3360&oldid=3359
5. There's some odd mistakes in the data. Network Rail has five regions, but in the stations
experience API, it has six. The sixth is - apparently - someone's name (which I'll omit for
their sake). I've not looked closely enough to know if there's other mistakes, but mistakes
like this make me nervous. The person in question at least doesn't have any lifts or escalators.
6. The API design feels a bit odd in places. It's light years ahead of CrossTech, but /stations
isn't a list of stations, you can only query individual lifts with respect to the location
it's part of (this is admittedly a nitpicky thing but it feels odd semantically), and there's
not a straightforward way to get a stripped down summary of lift status across all locations.
6. It's all REST, not a bit of GraphQL in sight. That was one of the most exciting things about
the new API for me, I quite disliked graphQL, and I disliked how opaque the API could be.
7. All of the endpoints work! Not a very high bar to clear, but that's where CrossTech set it.
8. You can now tell when a lift/escalator's status was last updated. You arguably aren't allowed
to do anything with this information, since you're obliged to only use the specified symbols
and text, but in theory this is nice to have.
If I were to summarise, I think that from a technological point of view, the new API is a leap
forward, but everything around it is a step back. I'm not currently willing to use the data in
anything public-facing - the restrictions are too onerous, and my feeling after the wiki debacle
is that enforcement is likely to be capricious and arbitrary.
Evelyn
I've finally had the chance to get to grips with the new Lift and Escalator API, I'll try to
summarise my observations. I'll start with the problems.
1. You need to email someone to sign up. Not the end of the world, but definitely higher
friction than many of the self-service APIs. The explanation for this (and other shortcomings)
appears to be that they intend to eventually offer it through the Rail Data Marketplace.
2. The initial information was extremely lacking. All you really had to go on were the two
documents you received if you were subscribed to the old API, which told you nothing about
endpoints or authentication. Peter had to go digging to work out the fundamentals, and I was
only informed of the URL for the public-facing API documentation earlier today.
The communication about the new API suggested that the documentation would be available via
Anypoint, with credentials available on request. When I requested it, I was told that it was
Network Rail internal only, but after some back-and-forth, was given - for the first time -
a link to the public documentation, a day before the old API is due to be closed down.
3. The mandatory protocol is extremely obtuse, it's effectively a requirement that you model
your interface around the interface of National Rail's access map, whether or not that's
appropriate. Some of its requirements are challenging - if not impossible - to comply with,
and some of the requirements are wrong; for example, you are obliged to say that the lifts
in Warwick Parkway, a station closer to Birmingham than London, are managed by TfL, or that
no live information is available in cases where this is untrue. I've expressed my concerns to
Network Rail, who say that the protocol may be revisited in future, with no commitment.
4. The contact at Network Rail who I was discussing this issue with requested that I edit
the article on the new API to remove the example API keys. I wasn't responsible for adding
these, but I mentioned briefly in my introduction that I was a contributor to the wiki. They
have acknowledged that the credentials are fictional, but nevertheless justified their request by
pointing to the first line in the terms and conditions:
"The credentials received are to be used solely by the person initiating the request unless
otherwise made clear during the request review process that the request is on the behalf of
another person or organization."
Since the credentials are entirely fictional, and generated randomly by Peter, not derived from
actual credentials, they are not "the credentials received".
To add insult to injury, the public documentation itself features example credentials. We've
changed the examples in the wiki to mirror those, I'm unsure yet whether this will be enough to
satisfy them.
I don't like feeling that I'm under pressure to make community documentation worse to accommodate
Network Rail's whims. They've bungled more than enough in their own communication/documentation
without insisting we join in.
My thanks to Peter for his guidance dealing with this.
Here's the diff:
https://wiki.openraildata.com/index.php?title=Stations_Experience_API&diff=3360&oldid=3359
5. There's some odd mistakes in the data. Network Rail has five regions, but in the stations
experience API, it has six. The sixth is - apparently - someone's name (which I'll omit for
their sake). I've not looked closely enough to know if there's other mistakes, but mistakes
like this make me nervous. The person in question at least doesn't have any lifts or escalators.
6. The API design feels a bit odd in places. It's light years ahead of CrossTech, but /stations
isn't a list of stations, you can only query individual lifts with respect to the location
it's part of (this is admittedly a nitpicky thing but it feels odd semantically), and there's
not a straightforward way to get a stripped down summary of lift status across all locations.
6. It's all REST, not a bit of GraphQL in sight. That was one of the most exciting things about
the new API for me, I quite disliked graphQL, and I disliked how opaque the API could be.
7. All of the endpoints work! Not a very high bar to clear, but that's where CrossTech set it.
8. You can now tell when a lift/escalator's status was last updated. You arguably aren't allowed
to do anything with this information, since you're obliged to only use the specified symbols
and text, but in theory this is nice to have.
If I were to summarise, I think that from a technological point of view, the new API is a leap
forward, but everything around it is a step back. I'm not currently willing to use the data in
anything public-facing - the restrictions are too onerous, and my feeling after the wiki debacle
is that enforcement is likely to be capricious and arbitrary.
Evelyn
Adam Williams
Feb 4, 2024, 2:36:33 PM2/4/24
to A gathering place for the Open Rail Data community
Hi Evelyn,
Thanks for this summary of the state of things.
the article on the new API to remove the example API keys. I wasn't responsible for adding
these, but I mentioned briefly in my introduction that I was a contributor to the wiki. They
have acknowledged that the credentials are fictional, but nevertheless justified their request
🤦♂️
> The mandatory protocol is extremely obtuse, it's effectively a requirement that you model
your interface around the interface of National Rail's access map
your interface around the interface of National Rail's access map
Which is this tool written in PHP by Fabrik, right? https://accessmap.nationalrail.co.uk/
Great .. except it seems to be completely broken at the moment. Screenshot attached is what I get when trying to check any station.
As far as I can see every single getPopupContent request it makes, regardless of the station, results in a content-length: 0 empty HTTP 200 and you get a loading spinner forever.
As well as being broken, it would also appear not to fully comply with the attribution requirements set out Open Street Map's license (no ODBL mention / link-through to copyright information).
Adam
Evelyn Snow
Feb 4, 2024, 3:34:19 PM2/4/24
to 'Adam Williams' via A gathering place for the Open Rail Data community
Hi Adam,
> Which is this tool written in PHP by Fabrik, right? https://
> accessmap.nationalrail.co.uk/
>
> Great .. except it seems to be completely broken at the moment. Screenshot
> attached is what I get when trying to check any station.
> As far as I can see every single getPopupContent request it makes, regardless
> of the station, results in a content-length: 0 empty HTTP 200 and you get a
> loading spinner forever.
One and the same! It doesn't work for me either, no doubt passengers will simply avoid being
disabled until whenever it gets fixed during office hours on Monday.
> As well as being broken, it would also appear not to fully comply with the
> attribution requirements set out Open Street Map's license (no ODBL mention /
> link-through to copyright information).
Beautiful irony
Evelyn
> --
> You received this message because you are subscribed to the Google Groups "A
> gathering place for the Open Rail Data community" group.
> To unsubscribe from this group and stop receiving emails from it, send an email
> to openraildata-t...@googlegroups.com.
> To view this discussion on the web, visit https://groups.google.com/d/msgid/
> openraildata-talk/f1ce29fd-4d39-4375-9dbf-b248e006cfben%40googlegroups.com.
> Which is this tool written in PHP by Fabrik, right? https://
> accessmap.nationalrail.co.uk/
>
> Great .. except it seems to be completely broken at the moment. Screenshot
> attached is what I get when trying to check any station.
> As far as I can see every single getPopupContent request it makes, regardless
> of the station, results in a content-length: 0 empty HTTP 200 and you get a
> loading spinner forever.
disabled until whenever it gets fixed during office hours on Monday.
> As well as being broken, it would also appear not to fully comply with the
> attribution requirements set out Open Street Map's license (no ODBL mention /
> link-through to copyright information).
Evelyn
> You received this message because you are subscribed to the Google Groups "A
> gathering place for the Open Rail Data community" group.
> To unsubscribe from this group and stop receiving emails from it, send an email
> to openraildata-t...@googlegroups.com.
> To view this discussion on the web, visit https://groups.google.com/d/msgid/
> openraildata-talk/f1ce29fd-4d39-4375-9dbf-b248e006cfben%40googlegroups.com.
Peter Hicks (Poggs)
Feb 5, 2024, 6:40:24 AM2/5/24
to A gathering place for the Open Rail Data community
On 4 Feb 2024, at 20:34, Evelyn Snow <eve...@kanaya.dev> wrote:
One and the same! It doesn't work for me either, no doubt passengers will simply avoid being
disabled until whenever it gets fixed during office hours on Monday.
Wasn’t the GraphQL API decommissioned very recently? I think it’s highly probable that the shut-off date wasn’t properly communicated and somebody was unaware of the problem until it was fixed earlier today :)
Peter
Evelyn Snow
Feb 5, 2024, 1:11:07 PM2/5/24
to openrail...@googlegroups.com
Hi all,
I've been doing more "finding out", and discovered a few exciting footguns in the API, not least
that boolean get parameters are validated (case-insensitive) before being compared
(case-sensitive), and behaviour there is a bit inconsistent, some typing issues too.
I've already mentioned how awful the list of stations in Figure 1 was, but since I needed to match
the stations to CRS codes anyway, I decided to generate a table as a byproduct.
https://wiki.openraildata.com/Stations_Experience_API/Figure_1_Stations
Evelyn
I've been doing more "finding out", and discovered a few exciting footguns in the API, not least
that boolean get parameters are validated (case-insensitive) before being compared
(case-sensitive), and behaviour there is a bit inconsistent, some typing issues too.
I've already mentioned how awful the list of stations in Figure 1 was, but since I needed to match
the stations to CRS codes anyway, I decided to generate a table as a byproduct.
https://wiki.openraildata.com/Stations_Experience_API/Figure_1_Stations
Evelyn
Hyphen Doubleyou
Feb 28, 2024, 1:08:19 PM2/28/24
to A gathering place for the Open Rail Data community
Perhaps one to add to the list of concerns, they appear to be gatekeeping access to to the new API for unclear reasons?
I had emailed them for access at the start of Feb, but didn't hear back. Chased them again this morning and have received the weirdest response:
As your email address seems to indicate that this request is for personal use can you please provide some more detail on how you intend to consume this data and the purpose for which it will be used.
Once we have received your reply we will consider your case and inform you of the outcome
My email address is personal@my_domain - I hadn't anticipated that would be an issue. Slightly stumped how to proceed now...
Evelyn Snow
Feb 28, 2024, 2:30:17 PM2/28/24
to openrail...@googlegroups.com
I also signed up using a personal email address, and wasn't interrogated at any length on that
point. Perhaps it seems more professional to them, but I worry that they might have decided to
be more awkward for other sign-ups.
Whatever the case may be, I think that playing this sort of game with accessibility information is
inexcusable. This data could be enormously beneficial to disabled passengers, it's ultimately them
that lose out with less community documentation, experience, and exposure.
I'd suggest putting to them that you plan to evaluate the API, if you've not got a concrete
use-case in mind yet. Let us know if they refuse you access, I'd see that as a serious problem.
Evelyn
point. Perhaps it seems more professional to them, but I worry that they might have decided to
be more awkward for other sign-ups.
Whatever the case may be, I think that playing this sort of game with accessibility information is
inexcusable. This data could be enormously beneficial to disabled passengers, it's ultimately them
that lose out with less community documentation, experience, and exposure.
I'd suggest putting to them that you plan to evaluate the API, if you've not got a concrete
use-case in mind yet. Let us know if they refuse you access, I'd see that as a serious problem.
Evelyn
> --
> You received this message because you are subscribed to the Google Groups "A
> gathering place for the Open Rail Data community" group.
> To unsubscribe from this group and stop receiving emails from it, send an email
> to openraildata-t...@googlegroups.com.
> To view this discussion on the web, visit https://groups.google.com/d/msgid/
> openraildata-talk/30c319c1-d538-4793-8ed5-fc04c3ca9fb4n%40googlegroups.com.
> You received this message because you are subscribed to the Google Groups "A
> gathering place for the Open Rail Data community" group.
> To unsubscribe from this group and stop receiving emails from it, send an email
> to openraildata-t...@googlegroups.com.
> To view this discussion on the web, visit https://groups.google.com/d/msgid/
Reply all
Reply to author
Forward
0 new messages