A closer look at the Lift and Escalator API v2

91 views
Skip to first unread message

Peter Hicks

unread,
Jul 3, 2022, 9:05:29 AMJul 3
to A gathering place for the Open Rail Data community
All,

I had an email in the past couple of days notifying me that the Lifts and Escalators API (which now seems to be at https://portal.nr-lift-and-escalator.net/, but I've not had any confirmation this is the correct URL to use, because the API calls are still made to https://nr-lift-and-escalator.azure-api.net/) has been updated and a new version is available.

In one of my rare moments of downtime, I've taken a couple of hours to look at it.  I don't think anyone from Hack Partners is on this list, so I'll be emailing them the feedback separately, but for the benefit of transparency for everyone else:

1. Apache HttpClient seems to have a bug where if you make an HTTP POST without any content (which is permissible, to my surprise!), it won't send a zero Content-Length header, and the remote server will send back a 411 Length Required.  Not a problem with the API as such, but I was also trying to send the x-lne-api-key in the POST body which didn't work either.  Likely my fault.

2. The JSON Web Token (JWT) returned from a call to POST /api/token appears to have an invalid signature.  It also includes a payload referencing "Demo User", and the user_id field of the JSON changes every time I request a new token.  I'm not sure what's going on here.

3. The 'Get Assets by Station Code' REST query fails with a validation error, even from the web interface, so something's wrong

4. The 'Get Sensors' REST query works, but has no data indicating where the sensor is located, because the 'Get Assets by Station Code' query fails.  Also, getting a list of sensors and no locational metadata seems a bit silly unless you already know where everything is

5. The 'Get Asset Info by ID' REST query returns an error, as it seems to want to use the 'publicFacing' field in the 'assets' objects which no longer exists

6. Introspection is disabled on the v2 GraphQL interface, which makes it tricky to explore given the documentation is lacking (and having documents on Google Drive isn't really that great, because you can't see when and what was changed in them)

7. The v2 documentation at https://docs.google.com/document/d/e/2PACX-1vTBUhyCXJoCvKUdIjE5GSyV3CqPgXg5d4K7DAghGilat4j8DTlWwMaTIQwTee-zvifFuW4NVB_0Hd5S/pub suggests a query under 'CRS codes' with the fields 'inCommision' and 'publicFacing', which aren't valid.  Remove these and it works.

8. The documentation suggests that more than 15 requests per minute will result in an HTTP 200 response with the error in the body.  An HTTP 429 'Too Many Requests' response would be more suitable, because a 200 suggests the API call worked... except it didn't

9. I can make GraphQL queries to /gateway/v2 without authentication, but I need authentication on /graphql/v2 - this seems like a mis-feature

10. The documentation suggests I need to supply the x-lne-api-key on both the token request endpoint (fine) and on the GraphQL query endpoint, and in the latter, I need to specify the bearer token as well.  In reality, I can get away with just specifying the API key, no need for the token.  Why do I need to request and send a token if it's not even used?

Hopefully anyone else running into these problems will now be aware of them and won't spend a couple of hours (or more!) of their time trying to troubleshoot.

Watch this space for updates.


Peter

Alireza Parandeh

unread,
Jul 4, 2022, 2:47:17 PMJul 4
to A gathering place for the Open Rail Data community

Hi Peter,


I'm Ali Parandeh - Product Manager and Software Engineer at Hack Partners responsible for the release of V2 Lifts and Escalators API.

Thank you for thoroughly testing the API, contributing to the API documentation and for your feedback on the V2 release! I appreciate the speedy feedback as we only released the V2 last Friday.

I've passed your feedback to the API team to rectify any of the bugs you've identified.


Please see my responses to the above queries below:


L&E V2 API Endpoints and Portal URLs

The L&E V2 Portal is located at: https://portal.nr-lift-and-escalator.net

In regard to the API endpoints, they should be listed beginning with the following URL: https://nr-lift-and-escalator.azure-api.net/

This is due the current limitation of the platform, but this may change. During our public preview and V1, we had to set up multiple endpoint URLs due to the technical limitations of the Azure platform we are using (not supporting graphQL and websocket subscriptions). We have collated a list of these endpoints on the API portal for the convenience and security of our users:

We never had initially planned to release the https://nr-lift-and-escalator.net/ endpoint to the public, however, we have made it available under the request of the owner of the API; Network Rail. We've had time to incorporate user feedback from our public preview V1 for the full V2 release, and continue to welcome more feedback!


Sending zero Content-Length header

Sounds like you’re attempting to send the x-lne-api-key header without a value?

We're not familiar with the Apache HttpClient setup - Do you have some time this week to have a chat about this for me to note down your experience and input?


 /gateway/v2  vs /graphql/v2 endpoints

The /gateway/v2 endpoint is a public access proxy (without signup) similar to that released to the public in V1 /gateway/v1 and we plan to continue this through our upgrade to V2.

/gateway/v1 endpoint is deprecated and will be removed from August 1st.

We wish to make the API available to all users without the requirement of signing up, by authenticating as an anonymous user. There are many reasons, such as testing the API, and why a user may not wish to or not be able to sign up. Please consider that the API is designed to be available for accessibility users who may have additional requirements.

Users who do not wish to sign up will not be able to:

- Access the new features (such as the stations table introduced in V2)

- Access the interactive portal for API testing

- Be notified of any changes to the API

- Have full access to the help provided by the website and help desk


All users will still benefit from any data fixes brought in by the V2 update.


Validation Errors caused by missing required headers - For instance, The 'Get Assets by Station Code' REST query  fails with a validation error

The validation error is what you receive when not the authenticated correctly. You require both your JWT token in Authorization header and your subscription key in x-lne-api-key header. This includes the stations endpoint that requires access to the stations table. We are investigating the limitations on sending detailed error responses using the current Azure platform setup.

This should be encompassed by the V2 API Authentication Docs, which are on the documentation.

 Any unauthenticated users trying to access the new V2 content will receive the validation failed error.


The 'Get Sensors' REST query endpoint

By providing the correct authentication headers you should be able to query the station assets and then Get Sensor Info By ID endpoint to receive the status of asset sensors. This endpoint is mostly used to create a table of sensors in a UI to investigate them one by one using Get Sensor Info By ID endpoint.


The 'Get Asset Info by ID' REST query endpoint

This is now reported to the team and fixed by the time of this response. The publicfacing field is no longer required.


Requiring both Authentication JWT Token + Subscription Key in GraphQL Endpoint

This is for security reasons. You can only generate a subscription key via the portal in a browser and generate your JWT token by passing your subscription token on the server to the /auth endpoint.

We feel it is safer to do the user authentication (name/id + password) on the API portal, rather than transmitting personal user information across different cloud instances. The GraphQL endpoint asks for a pair of keys to ensure the client and their server are both authenticated.


inCommission and publicFacing fields

In V2 API only public-facing and in-commission assets are returned by default. Therefore, these fields are no longer exposed in the V2 public API. We have made adjustments to the inCommission and publicFacing fields on the documentation, since these are not fields available to all users.


GraphQL Schema Introspection

On V2 the schema introspection is disabled for security reasons but can be viewed through the GraphQL console in the portal: https://portal.nr-lift-and-escalator.net/api-details#api=graphql-api-test


V2 API Documentation

I understand the documentation can be improved. Would you please be able to provide specifics on how to extend it?


Demo User shown in JWT + API Rate Limit Reached Error Response

Thank you for this report - These have been identified as bugs by the engineering team. These should not affect anyone using the API. I've passed these to the developers to see if this can be addressed.

The user_id is mocked as we validate only using a key from the server and client to validate your user permissions on the API backend - hence the required x-lne-api-key. We feel it is safer to do the user authentication (name/id + password) on the API portal, rather than transmitting personal user information across different cloud instances. We can look into the issues with values of the JWT token headers such as user id, however, it is not required for validation.


Further issues & Feedback

I encourage all to reach us at networkra...@hackpartners.com for reporting further issues. I will make sure these are addressed to improve the quality of the L&E V2 API and documentation.

Ali

------------------------------------------

Hack Partners Limited is a company registered in England and Wales. Registered Address: Hack Partners, 10 Market Place, Devizes, Wiltshire, England, SN10 1HT. Registered Number: 9274301.

 

This e-mail, and any files transmitted with it, are confidential and intended solely for the use of the individual or entity to whom it is addressed. If you are not the intended recipient, you are notified that disclosing, copying, distributing or taking any action in reliance on the contents of this information is strictly prohibited. If you have received this e-mail in error, please notify the sender by return and then destroy it.

 

The views and opinions expressed in this email are the author’s own and may not reflect the views and opinions of Hack Partners Limited.

 

This e-mail message has been scanned by antivirus software, however Hack Partners Limited cannot guarantee that it is virus free.

Reply all
Reply to author
Forward
0 new messages