#605: App history API

Visit on Github.

Opened Feb 2, 2021

HIQaH! QaH! TAG!

I'm requesting a TAG review of the app history API proposal.

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 window.appHistory API, which is more directly usable by web application developers to address the use cases they have for history introspection, mutation, and observation/interception.

The proposed 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, 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 API Design Principles
  • The group where the incubation/design work on this is being done (or is intended to be done in the future): WICG
  • The group where standardization of this work is intended to be done ("unknown" if not known): WHATWG
  • Existing major pieces of multi-stakeholder review or discussion of this design: none of this design, although there is a lot of discussion of how the existing history API is bad (which the explainer links to throughout)
  • Major unresolved issues with or opposition to this design: no major issues yet. There are a number of minor TODOs scattered throughout the document and issue tracker; thoughts on the best ways of resolving those would be appreciated.
  • This work is being funded by: Google

You should also know that...

The intent here is not to provide any substantial new capabilities, but instead provide a more ergonomic and interoperable API for manipulating history. See especially our discussion of interop goals and building this on a solid foundation at the bottom of the explainer's Goals section

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

2021-03-08

Minutes

Dan: early in the design process and they will come back for further review after.

Ken: making sure that the right use cases work, the current history API is really broken for app experiences. If you want to do something like twitter with different tab but you want each tab to have a different URL that you can share, but you want to click back, but you don't want if you click between tabs and press back it goes between them. In native apps you go one back. Making those experiences and still getting a shareable URL is really complicated. You end up with an experience where people press back and it closes the PWA. Or it's cycling through tabs and you don't know where next.

.. the main problem is the browser inserts things into the history out of the apps control. Solving by history created directly by the application. It's important.

Dan: scoped to same origin

Ken: like what you can do today but better

Amy: read the s&P questionnaire response and half the explainer and nothing jumped out...

Ken: not loading a separate HTML file but changing the URL and showing a different UI

Dan: no feedback from gecko or webkit

Ken: looking at all the details and use cases will take some time. feedback on initial impression

2021-03-15

Minutes

Ken: haven't had time to look in detail. It's really big.

Dan: feedback from domenic 6 days ago. He left four points about where to focus our review.

Ken: not easy questiosn to answer.. the API is designed around the weirdness of some APIs so replacing them would mean re-adding weirdness... could be done as an opt in, but something I have to think about. I can look at those issues. ... First one is more of a question to web devs than it is to us. Issue 66. Web developers might nt want to update the address bar immediately, but I don't know what the use cases are, I'm not one of those developers who don't want it to update..

Dan: we can try to channel the needs of web developers.

Ken: they don't know if anyone is doing it.. you'd want to include people working on routing frameworks and things like that. I could ask my friends at ionic if this is something..

Dan: I get nervous any time we start talking about rewriting the URL bar. I need to re-review security & privacy quesitonnaire and considerations section. I recall being pleased with what I read there but don't remember what.

Ken: asked someone working on angular.

Dan: are they doing anything with the URL bar that can't already be done with the existing history API?

Ken: can't do that today because you're changing the state. By not having push state in this new API might be an issue.

Dan: making a note about potential for misuse. Discuss more at plenary, can bump to next week.

Ken: adding some comments into their issue (the ones linked)

2021-03-22

Minutes

Ken: I added people from Angular and Vue to comment - they are going to look at this in detail... I think we should let it be for a while...

Dan: mixed signals about how urgent this is

Ken: needs to work for developers or it doesn't make sense. People who work on frameworks are looking now, which is better feedback than what I can provide. See what they say instead of me trying to come up with feedback.

Dan: it looks like dominic did make a change to the explainer that clarified the issue that I raised about privacy and security about spoofing URl bar (really good). If we could indicate in our issue that this work is going on that you mentioned so we show some more progress

Ken: their issue 66 there is discussion. Will link to our issue.

Dan: we can bump this issue a couple of weeks and come back to it.

2021-04-19

Minutes

Sangwhan: curious about traction from other implementers. I like the idea.

Ken: I thimk it's for single page applications - which do work in every browser....

Dan: can this be used to spoof the url bar because we're talking about modifying history? Dominic clarified that and made a change to the privacy & security to indicate that. That was the main issue I saw. Felt inherantly worrying when you talk about something that is an API onto the browsing history. The word "app" is unfortunate in the name. Looked to me like that had been thought through in the spec.

Sangwhan: I wasn't particularly concerned about that.

Dan: Ken asked framework authors to look at it

Ken: posted links to feedback

Dan: what next? They're asking to close up the review, is there more to do?

Ken: they have good questions in issues, whether we have comments on those instead. Dominic filed a lot himself. NavigateState option... something we have some opinion about?

Dan: key things they asked from us are about when url bar updates, reporting navigation duration, replace window history and window.location, and should apphistory events be fired on page load?

Sangwhan: usually the origin that matters for users?

Ken: sharing a URL, then it matters. Regular users don't look at the URL but they do share it

Sangwhan: share goes to another view, the share view

Ken: but you have the full URL, eg. with a tweet so the twitter view inside the SPA.. the tweet not the whole thread ... Normally framework around history API, updates the URLs..

Sangwhan: feels somewhat random from a users perspective

Ken: lots of SPAs do it really well so they update the URL when you're changing the view, especially so you can copy the URL and it makes sense. Or refresh you stay the same place

Sangwhan: I've seen a lot of SPAs do that extremely wrong

Ken: if you don't know/think about URL and state...

Dan: it's about giving control to the developer, so they could use it to do something that doesn't make any sense. But ideally it's about servicing a user need which is that what happens in the history and in the URL bar makes sense wrt what the user's expectation is about that appication. Sharing/refreshing/copying are all things that give the user agency.

Ken: today it's quite bad. All those routing framework have to hack around the existing API, so once in a while it breaks in unexpected ways

Sanghwan: that's what I meant about random

Ken: new API makes it easier to do this the right way. I have dealt with this in SPAs and it's a pain. Don't like pulling in these huge router frameworks that I don't understand.. I want to do it without relying on a framework and know what's going on.

Sangwhan: even if it's not super friendly to handroll everything being able to do it at a framework level in a way that doesn't look random is progress enough to justify this work. Right now it's not work. Would be great to use from the get go though

Ken: i think you can, that's what they're trying, it's not just for frameworks. They want to make an API because people are using frameworks so they can subsittute this API and have less bugs. But also an API for develoeprs who want to knwo what's going on. That's the problem with those routing frameworks, t ey expect your app to work in a specific way and sometimes that's not what you want. Having an easy to use low level API is realy progress.

Hadley: I don't mean to throw a spanner in the works.. Agree with what Ken and Sangwhan and Dan are saying that ultimately this makes things make more sense to users. We are spending a lot of energy in FPS saying users have built up an understanding of how the web works that hinges on some basics like having a vague sense of what an origin is... we're not too far away from all that stuff. In letting developers redefine the back button we are in redefining what back goes to, rather than going to the previous page ..

Ken: you can do this already

Sangwhan: it just sucks

Ken: not changing anything. People are doing this today.

Sangwhan: it's not great and this is why we're happy to see this

Dan: I have the same visceral reaction to this which is wait you're mssing with the history. But on the other hand, many web applications are built using this design pattern and

Sangwhan: damage is already done, harder to find an application that doesn't do this these days..

Hadley: As a user this makes sense, that's really important, we should focus on that. May be logically inconsistent.

Dan: What does multi engine support look like? I was going to leave a note about that. Otherfeedback on the points Dominic has specifically asked about?

Ken: they're getting feedback from developers... [on #66]

Dan: they're asking for feedback on the user experience of when URL bar updates..

Ken: if it's moving to another domain ti should update immediately

Hadley: I agree

Dan: that's feedback we can give from a how the web works perspective, reinforcing importance of origin.

Sangwhan: you can't change the origin with this API can you?

Dan: no

Hadley: having an accurate URL seems pretty important

Ken: people have use cases like...

Hadley: Dominic says some people might want to use it if it changes the URL sooner.. but I don't understand why

Dan: the point is if you have the URL bar update you can make use of it. You go to a single viwe of a tweet you want the URL bar to be the tweet not the previous thing

Ken: angular and vue router work the same way.....

Sangwhan: youtube updates with time, but not the history...

Ken: same as google maps, stores coords if you move map.. copy it you get the local one but probably replacing the entry in the history

Sangwhan: cases like that they won't use this API..

Ken: it's the same, your'e just replacing, so you go back and forward you go around the map..

Sangwhan: makes sense for map, not for video..

Ken: why not? updates timestamp.. you press forward and want to go to the same place in video if you clicked back by mistake, or clicked a video you didn't mean to.. don't want to start from beginning..

Dan: could we say updating immediately makes the most sense from a web ux point of view?

Ken: vue and angular routers don't do that

Hadley: useful to ask Dominic what use cases where this would be bad

Ken: or ask them to explain how that works.. should there be a timeout? how long can you defer it? a few milliseconds? I'm going to ask.

Dan: will ask on our issue and reference their issue

Ken: #33 .. for performance? Seems reasonable to reuse performance entry if that's being used for everything else.

Sangwhan: there is no way to measure as of today? Agree performance entry.

Dan: if it's already being used in a similar way elsewhere then yes

Sangwhan: not the same but close enough that it makes sense. Likely it will fetch.. navigation pulls in new data in a lot of cases.. not the same computational complexity as loading a new page from scratch

Ken: [leaves comment on issue]

Dan: #67 should this API replace window.history and window.location ?

Ken: would be nice..

Sangwhan: would be very nicei but we can't get rid of window.history...

Dan: what's the decision point? Can't we let this be organic? If developers embrace this API then eventually window.history could be deprecated?

Ken: that's why it would be nice. Question is a few things with the API you cannot do? or will people stop doing it, or so important they cannot use this API?

Sangwhan: one thing is restoring scroll. I can see how that doesn't fit into the current design

Ken: you also want that for bfcache navigations right?

Sangwhan: it's not done thorugh an API, the user agent does that for you. If it's not a proper page it will probably put you in a weird state.. I don't know how that should work here

Ken: no counterpart to push state or replace state.. issue for youtube and maps? [leaves comment]

Dan: what other decisions are gated on this question? Do we need to decide as a platform right now? is he saying they need changes to API now?

Sangwhan: to take into account stuff like scrolling you might have to redesign certain parts of the API surface which would be difficult once you ship. I'm not entirely sure how pushState and replaceState would be replaceable with this. It covers most use cases but I don't know them all to comment on whether it would work. There's also the frames problem. window.history supports frames. If you do iframe navigation it goes onto window.history. If you press back a couple of times and you've navigated within the iframe it navigates the iframe then to the parent document. This API does not account for that. We might want a separate breakout on this..

Dan: plenary? We could ask Dominic to join us for a discussion? See if you can schedule a time Sangwhan?

Sangwhan: I'll reach out to him and read up on all of their other issues.

2021-04-26

Minutes

Dan: Dominic commented 6 days ago on the topic of whether the URL bar should update immediately... sites today delay updating URL until after data is fetched and DOM updated..

Ken: they are waiting to hear from authors

Dan: should we keep this open?

Sangwhan: last week we suggested we might want to have a separate call? I was supposed to arrange

Dan: if we've got something really helpful it's worth having a separate session but looks to me like they've got it in hand. He's spoken to people at Mozilla.

Ken: I don't have anything else

Sangwhan: I don't have anything at the moment

Dan: let's talk about closing in the plenary or maybe waiting on updates and rereview at some poin

2021-05-Arakeen

Minutes

[naming is hard]

Hadley: something about how all the javascript options change how your back button works

Dan: there is already a history API, we can't call this history API but it provides additional functionality, why isn't this just a revision..? There's a mechanism in place for creating new versions of APIs.

Tess: part of explainer that talks about integration with existing history API

Rossen: is the scope the same?

Dan: if it's not is the history api currently being worked on? Developers trying to wrap their heads around the different APIs... not the history API, the App History API... this is a problem.. we keep adding new things without reivsing the existing things

Tess: sympathetic to this in general. In the case of fetch, we couldn't just remove XHR. XHR is a mess.. what we did was designed a new model that unified sub resource fetching and came up with a clean api and it was worth the redundancy, and we have to live with that forever because of compat. Does the same reasoning apply here? We can't remove the old history api..

Dan: I don't think so, the old history api does something different.. they both manipulate history

Tess: in the spec it says it's layered on top of existing history api

Peter: says the existing concepts, not the API.. not inventing new notions of what history is

Tess: in that case it sounds like XHR and fetch. There's a legacy API and a modern API built on the same underlying model. In XHR and fetch from a developer standpoint it's easy to know which to use... the existing one has a really obvious name which is exactly what you want, whereas in the case of XHR it was this bizarre thing

Dan: this is flipped.. history is the thing we want it to be named, app history is confusing

Tess: right, what do apps have to do with it. Do we have another example of doing this in a good way?

Dan: my primary concern is developer confusion. has something to do with naming, but also the proliferation of new APIs.

Tess: reassuring to see they didn't add an incompatible mechanism. Sits on top of current model. Agree it's worrisome that in a world where these two APIs exist the one we want people to use is the weird named one and the one we don't want people to use is the obvious named one.

Peter: options are extend existing history model or break existing code... if they're different enough, extending existing history doesn't make sense. Could be a sub object. history.altview or whatever..

Rossen: prior art to similar patterns, pointerevents and touch events came to mind and how one took over the other over time. Similar naming and concepts, one being a lot more extensible, future proofed than the other, shipping later, consuming the other. In that case we went with completely different api naming rather than trying to reuse touch events.

Dan: we have given comments, at least one is addressed and merged. Got some framework authors to comment. More value we can provide? Should we say we think there's an issue with the name, appreciate the work, no additional feedback?

Peter: very happy to see an effort to make a better history API.

Rossen: design intended to be a lot more pleasant. We can't overhaul history in its existing state. We'll see what they come back with in terms of bikeshedding.

We're happy to see this effort happening. Thanks for listening to our feedback. Adding additional complexity to the web platform remains a problem. We're concerned about adding a new API that has to do with history which developers will find confusing on top of the existing history API. At the same time it's clear that it's meeting a user need. The example of XHR and Fetch came up in our discussion. In that case, it was clear what we were asking developers to do - migrate to Fetch. Can we do the same with this API? So we'd like to better understand how this can be added to the web platform whilst also mitigating against the complexity issue. However we're generally happy to see this go forward.

Dan: it's more than the name. Are we telling developers don't use the history API, use this new thing, or history for one set of things and new history api for other set of things