#717: Navigation API (formerly app history API)

Visit on Github.

Opened Mar 8, 2022

Braw mornin' TAG!

I'm requesting a TAG review of the proposed navigation API.

The web's existing history API is problematic for a number of reasons, which makes it hard to use for web applications. This proposal introduces a new API encompassing navigation and history traversal, which is more directly usable by web application developers. Its scope is: initiating navigations, intercepting navigations, and history introspection and mutation.

This new window.navigation API layers on top of the existing API and specification infrastructure, with well-defined interaction points. The main differences are that it is scoped to the current origin and frame, it has a different flow for implementing single-page app navigations, and it is designed to be pleasant to use instead of being a historical accident with many sharp edges.

Further details:

  • I have reviewed the TAG's Web Platform Design Principles
  • Relevant time constraints or deadlines: we are hoping to send out an Intent to Ship before April 14, 2022
  • The group where the work on this specification is currently being done: WICG
  • The group where standardization of this work is intended to be done (if current group is a community group or other incubation venue): WHATWG (HTML Standard)
  • Major unresolved issues with or opposition to this specification: no major issues. Some minor issues in https://github.com/WICG/navigation-api/milestone/1 which I am setting up a working session with Mozilla to nail down.
  • This work is being funded by: Google

You should also know that...

This was previously reviewed in https://github.com/w3ctag/design-reviews/issues/605. Based on TAG and Mozilla feedback, we had a renaming discussion in https://github.com/WICG/app-history/issues/83 which led to the new "navigation API" (and window.navigation) name.

We'd prefer the TAG provide feedback as (please delete all but the desired option):

🐛 open issues in our GitHub repo for each point of feedback

Discussions

Discussed Apr 1, 2022 (See Github)

punted

Comment by @hadleybeeman Apr 13, 2022 (See Github)

Linking to our previous review on App history API

Discussed Jun 1, 2022 (See Github)

re-reviewing the explainer

Dan: wondering about privacy - what if the user has a private session with the web site in question and also a non-private-browsing-mode session? Can data leak in that case? No mention of private browsing or incognito.

Dan: Generally concerned with any API that deals with history as this can be privacy-impacting.

Lea: it's being prototyped so we could play with the navigation and get first hand experience in using it...

Dan: a little unclear about the impact on the back button user agent UI section of the explainer.

Dan: a little unclear on the joint session history I think the definition needs to be expaned or if it's defined somewhere else then there needs to be a linked.

Peter: history interface on window() - the overall history of the browser.

Dan: but this API is origin bound -

Lea: need to be contiguous as well - only see the history entries from the latest browsing session - which seems reasonable.

Dan: would that address the private browsing mode issue I raised?

Peter: it would create another top level browsing context. Since this is related to the current session on this document it couldn't talk to another session in a private window or vice versa. And if you go from A to B back to A 2nd instance of A can't see earlier entries from A.

Lea: it's a very large API. The basic stuff seems reasonable.

Sangwhan: I looked at this and it looks like a good idea. API looks fine to me.

Lea: it's scoped to a single window. Private browsing is a red herring because even in normal.

Dan: they have answered "no" to the private browsing mode question in S&P questionnaire...

Sangwhan: in some browsers you can re-open a closed private tab - behaviour isn't standardized there.

Lea: in chrome's implementation if you close a tab and re-open it the history is preserved - including in the navigation API.

Dan: is that desirable?

Lea: Yes.

Sangwhan: yes.

Sangwhan: I'm positive - I've used the alternative - push state. and this is an improvemt.

Lea: I'll second that.

Hi Domenic - sorry this took so long.  We've been reviewing and have had the chance to discuss on today's call. Some feedback from that session: In general we're happy with this API. We appreciate the care taken in the security & privacy considations section. One question I had was about how this impacts the behaviour of the back button - it wasn't exactly clear what you mean by "when iframes are involved" here. Can you spell it out a bit more clearly?  Is this to do with the iframe's navigation history being integrated with the parent document's history?  And what is the changed UI you anticipate?  Generally we have positive feedback. This looks like it will be an improvement over the current state of the platform. We're planning to finish the review and close next week.

Dan: posted

Discussed Jun 1, 2022 (See Github)

Sangwhan: are we happy with this api? I had a followup question. "If the frame is first-party and the content author would like to delegate history down (to the frame) and then back up, how would that work? Obviously this is a bit of an edge case, but mostly asking out of curiousity"

Sangwhan leaves comment and we will try to close at the plenary

Comment by @domenic Jun 13, 2022 (See Github)

Just leaving a quick note here about an upcoming breaking change we're making. I don't think it needs a separate TAG review but it might be interesting for the group: https://github.com/WICG/navigation-api/pull/235

Comment by @torgo Jun 22, 2022 (See Github)

Hi Domenic - sorry this took so long. We've been reviewing and have had the chance to discuss on today's call. Some feedback from that session: In general we're happy with this API. We appreciate the care taken in the security & privacy considations section. One question I had was about how this impacts the behaviour of the back button - it wasn't exactly clear what you mean by "when iframes are involved" here. Can you spell it out a bit more clearly? Is this to do with the iframe's navigation history being integrated with the parent document's history? And what is the changed UI you anticipate? Generally we have positive feedback. This looks like it will be an improvement over the current state of the platform. We're planning to finish the review and close next week.

Comment by @domenic Jun 22, 2022 (See Github)

Thanks for the feedback, and I'm glad to hear you all feel it's an improvement!

One question I had was about how this impacts the behaviour of the back button - it wasn't exactly clear what you mean by "when iframes are involved" here. Can you spell it out a bit more clearly? Is this to do with the iframe's navigation history being integrated with the parent document's history?

This is spelled out in a bit more detail in https://github.com/WICG/navigation-api/blob/main/README.md#correspondence-with-the-joint-session-history . It is indeed about how the iframe's navigation history is integrated with the parent document's history, and how that makes programs harder to reason about even if it can give a better user experience.

That integration remains true for the back button and thus for the user's experience. It also remains true for the classic history API's history.back(), history.go(), etc.

The new feature of the navigation API is that if you use it, then the developer only has to deal with their own frame's history. I.e. instead of how the classic history API has you traverse through the all-inclusive history entry list, with the navigation API you get separate history entry lists for each frame. The section I linked above has specific examples, including what this means for navigation.back() behaving differently than history.back().

However, implementing the navigation API does not imply any UI changes, or changes in the behavior of the back button.

I hope this helps, and am happy to clarify more. Other relevant sections:

Comment by @cynthia Jun 28, 2022 (See Github)

Thanks a lot for the clarification! If the frame is first-party and the content author would like to delegate history down (to the frame) and then back up, how would that work? Obviously this is a bit of an edge case, so mostly asking out of curiosity.

Regardless of an answer to that question, we are very happy to see this proposal move forward.

Comment by @domenic Jun 28, 2022 (See Github)

I'm not sure what you mean by "delegate history"; could you expand on that?

Comment by @cynthia Jul 14, 2022 (See Github)

Ah, so the question was how to get the parent document's navigation stack needs to cooperate with a frame's navigation stack - I wasn't sure by looking at the proposal.

That said, we can take this offline as we are happy whether or not that question is answered. Thank you for bringing this to our attention!