Creating and maintaining front end APIs

Thank you.

Yes.

Yes.

that sounds very official.

Absolutely.

Listen to everything that I have to say.

my talk is on, front end APIs.

I'm going to tell you a bit about when you might want to build a front-end API and a few things that you should take into account while doing so.

And first I want to tell you a story.

So very long ago at the beginnings of the internet, People used to hand code their websites from scratch.

So there was no way to build a website without actually writing all the code yourself.

And that is a screenshot of, from internet archives, cache of geocities websites, which is super interesting.

I, recommend you go have a look at it.

There's some really great stuff in there.

But maybe let's not go that far back.

Let's go.

Maybe not as long ago as that, but right to the early two thousands, which is the beginning of Web 2.0.

And at that point in time there was this Web platform called MySpace.

And some of you may have heard of it.

And what I want to tell you about MySpace is that, they existed as a platform.

they hadn't existed as a platform for very long.

When quite by accident, they discovered what all their users really wanted was to be able to customize the hell out of their online presence.

And I say that they discovered this by accident because initially MySpace didn't realize that.

The Input field that they had provided users so that they could add a user profile, accepted and not only accepted, but output directly to the front end any and all HTML that you added to it.

so the problem with this gaping security hole is that by the time that MySpace realized that this was happening, users were customizing the hell out of their websites, and there was so much creative stuff going on here that they, just, they couldn't, if they stopped this, then everyone would just go find somewhere else to hang out because this was the major feature of MySpace.

I'd like to say that this is the beginning of website theming.

It's a bit more than that actually, because this tool, this accident, enabled a whole generation of folks to learn the basics of HTML and CSS, which is actually pretty great.

So how it worked was you could add HTML tags.

So you know that if you add, if you can add HTML, you can add CSS, you can add scripts, you can add all sorts of stuff.

And so the main strategies, there were two basic strategies.

You could either add CSS that would customize the HTML that MySpace provided, or you could add your own markup and you could absolutely positioning on top of what MySpace provided and then just hide the MySpace's existing markup.

So there were these two strategies.

And so let's think about this in terms of frontend APIs.

Is this the first frontend API?

Is this like the beginning of theming APIs?

I'd like to think that, uh, a dev just overlooking sanitization of user Input is not really an API being born, but there is some, okay, maybe I'm getting ahead of myself.

Let, me explain what, an API is here, and I'm going with a very loose definition, which is an API is an interface between two applications or two pieces of code really, if you want to get really basic about it, and I know that people like to talk about contracts in the context of APIs.

What a contract really is, documentation.

there's, there is nothing legally binding you as a maintainer of an API to keep that API working and not break everything.

you, can do breaking change.

So APIs are just, a point where two pieces of codes come into contact with each other and the way that happens.

So in this case, you could say that you, you have a bunch of people writing programs, which are customizations for their MySpace page, and you have the platform, which is MySpace, being customized, so being extended by these customizations.

So the real API that you have here is, the markup that MySpace provides, because that's the point at which the extenders are hooking into MySpace and they're providing their stuff on top of it.

It's what enables them to make changes to MySpace.

Changes on top of, yeah.

Yeah.

So that's what, it's all about.

It's personalization.

Personalization is like what everyone wants, on the internet apart from cat pictures.

Cat pictures are the number one thing that everyone wants to see on the internet.

The second thing is you want your Web presence to be personalized.

And the way that we do that nowadays is through theming.

Now there are, I'm going to, there are many ways that this could go, but I am in this talk, going to discuss, two possible use cases for theming, which are pretty major ones.

So one is themes for websites.

So if you build a website in particular, if you are using a content management system or could be an e-commerce platform, any tool that allows for a website to be built and put online, you will probably want to install a theme on it that will customize the way that website looks.

personalization.

So that's first case.

And the second case is, slightly different.

It's more user facing.

So in a website theme, you would be like the owner of the website and you customize your website so people can see it in that way.

Application themes work a bit differently because they are themes that a user of an application will install so that they can customize the way that they are seeing that application.

So it's more of a personal case, and in both of these, situations, the either the platform that's, That's allowing you to build a website or the application that allows you to theme it will provide some kind of theming API.

But for both these cases, and that's why I want to look at them separately, the APIs can look quite different.

So let's look at website themes first and yeah, apparently I work on WordPress Core, and so I want to do a shout out to the, creators of the WordPress pixel theme, because I totally ripped off the aesthetic for these slides from that theme, colors, fonts, everything.

So thanks to them, I'm not, really that good at design.

and I'm going to actually show a few WordPress examples.

Not all of the examples here are WordPress, but quite a few are for obvious reasons.

Okay?

So website themes.

One.

so one very, distinctive factor about theming for websites is that usually you will have to provide some kind of templating system.

And this is because, for a website theme, you, theme authors will want to create layouts.

They'll usually be writing the HTML and they'll need some tool that allows them to render content inside that HTML, and that could be a templating language or like it could be just a bunch of functions that grab the content from the backend and allow you to render it in the correct places.

So let's start with an example.

This is actually, with, it was made with liquid.

Liquid is an open source templating language created by Shopify, and it is, it's pretty handy.

That example does not come from Shopify.

It comes from Jekyll, which is a static site generator that uses Liquid too.

And so you can see that what's happening here is that so this is what the theme template markup would look like, and you have a bunch of HTML, and then inside that HTML you have a bunch of tags.

So you have like site.title, which is where the site title is going to render.

You also have a few tags that provide logic, so you can go, ah, is, there, is this a page?

Does it have a title?

Maybe render the site title just as an anchor tag.

If it's not a page, if there's no heading on that page, then just render the site title as an h1, and that's the sort of common practice when you want to write semantic HTML.

And you only want there to be one level one heading on the page.

And that looks pretty neat and easy with liquid.

It's a very front end friendly solution, because the tags just make it very easy for you to write the mark up and put everything in its place.

Now, the second example is a bit different from that.

This is an example taken from WordPress.

And what's happening here is there's, that WP_Query is a class that exists in WordPress that basically it takes a bunch of, um, requirements and it fetches data from the backend.

So it just directly queries the database and you give it an array of the things you want it to query, and then you can grab what, what it returns.

And you can have your markup and then you can render, say that's like a loop of posts being rendered from the results of that query.

And this looks like a much more complicated approach and potentially less dev friendly.

when would you maybe want to use either of these?

The thing, the main thing to take into account, the distinction between these two examples is.

Do you know, oh, as a creator of your theming API, do you control exactly all the types of data that, that your backend has to offer?

So if you are in a previous example, maybe all your backend has is like a page object and a site object, and that's it.

So that's, very easy.

Because you can write your templates and then they get parsed, in the backend, they get fed those two objects and then the they'll render with the correct data in place.

The thing about WordPress is, it allows you to create custom data types.

So you can have custom post types, you can have custom taxonomies, you can have metadata for the posts, all sorts of things.

And so as the builder of the API, you have no idea what's in the database at any given time.

You have no control over all the different types of data that might be in there.

And so it's useful to provide this catchall tool that allows you to just query for that data directly, whatever is in there, you can fetch anything that you want.

So that's the main differentiating principle there.

Now in either of these cases, what we are seeing is a bunch of either tags or functions that allow us to grab data from the backend and render it in the markup that the, theme author will write themselves.

Things start to get interesting when you have function.

theming or templating functions that actually render their own markup.

So this is another example from WordPress.

You can see that there's, a navigation tag, a nav tag in HTML.

And inside that nav tag, we have a chunk of PHP that's running this wp_nav_menu function.

And what that function does is, provided, a navigation that a user has created, which would be a bunch of links.

That might have sub menus, so it might be a nested bunch of links.

What that function does is it goes through those links and it wraps them in an unordered list, and what it outputs is the unordered list, possibly with nested unordered lists, with sub menus if they exist, and it will give it a bunch of class names and, the thing is that you can, as a theme author, you can actually tell that function to output different markups.

So you can custom, if you don't want it to be wrapped in the list, it doesn't have to be, you can customize the output, but it's such a sensible default that most themes actually just end up going with it.

And, that is, uh, what happens here is that as, the, API provider from the moment that you are outputting markup, you have, you are like widening the surface area of your API because all that markup becomes an API.

And this is because the markup has to be styled.

So when a theme author creates all their own markup, they're responsible for that sort of that communication between the markup and the styling.

So they'll add the stars to their markup and, that's all sort of their logic.

But when the platform is providing the markup, then they have a responsibility towards theme authors to keep that markup going, not, make breaking changes, at least not make breaking changes too often.

it's not, as I said before, it's a contract isn't binding in any way, but it's nice to, be nice to the people that extend your platform.

So the thing to take into account, I think is mainly just be aware that markup is going to function as an API.

And one thing that I find quite useful is to think mainly in terms of class.

So class names are probably the best way to go here because if you are providing a bunch of markup to be styled, uh, if you have nice semantic class names, people are going to grab those and they're going to attach the stars to those.

If you don't, then things might get pretty messy with, trying to target specific HTML in this specific position.

And yeah, it can get weird.

So that's, I guess the, best way to approach that sort of situation.

However, there are other ways.

And so the next one I'm going to show you is, how WordPress is doing things now, which is, the with the block editor, I dunno if you've heard, this is like the current text editor for WordPress is this kind of drag and droppy interface where you have content blocks and you can just add them to the page and create your own Layout.

It started as a post editor.

and now it's expanded to be a whole site editor.

So you can basically create your, all, your whole website, you can create all your Layout with these drag and droppable content blocks.

What this means is that WordPress is basically providing all the markup for theme building because a theme can all be built out of content blocks with preexisting markup.

And that is setting us up for a lot of back compatibility grief, potentially.

whoops.

So we found a solution to this, but first I'm going to show you how the markup works.

so this is what classic, in a classic WordPress theme where you would write your markup yourself with PHP logic.

That is the whole logic that you would use to render a site title as an h1 in your homepage where you probably don't have any other heading tags and as a paragraph tag or an anchor wrapped in a paragraph tag on your other pages where there's a, great likelihood that there will be other heading tags.

So that's a whole bunch of logic there.

With the new system, this is exactly the same logic, except the only thing that the theme template has to have in it is that HTML comment that it tells you that it's a site title, it's a site title block of content, and then the bit inside the curly brackets is in an attribute with the level.

And what that means is if it's level zero, then it's not a heading at all.

And then you could have level one to six, which would be the several levels of headings.

So that's a lot easier to write.

But the best thing is that theme authors don't even have to write that markup by hand anymore because we have this nice UI where they can just compose the whole theme out of these content blocks, and then they can export it as an HTML file.

And so the theme can be bundled with these HTML files that were created with a, with this nice little ui.

Yes, but how do we solve the problem of, we are now outputting all this markup and theme authors are going to style it, and so we're going to be stuck supporting that same markup forever.

Cause sometimes you do need to change markup.

And so we came up with this styling API.

When I say we, WordPress, I tend to just refer to it as we, I hope it's not confusing because I'm like the thing I work on.

so how do we abstract this styling API in a way that means that we don't have to support all the, like the, first crappy markup that we wrote forever.

What we came up with was a JSON file, and this JSON file, allows you to, for each kind of content, block set, styling settings, and apart from the, you can target content blocks, but you can also have sitewide settings.

So you've got that appearance tools is actually enabling a bunch of, tools to be rendered in the interface so that users can customize the appearance of their, content.

So that's on top of the theme.

And then you have, you have settings like content size and that will output a couple of lines of CSS, which be, max width of something and maybe some margins depending on whether it's centered or not.

You have even more abstract concepts like a color palette that you can define and then that can be used in, the UI settings.

You can have, you can provide all these colors that sort of are designed in a way to look good with each other on the theme.

And so some of these, for instance, in the block, you have font family, font size, those, each of those corresponds with a discrete line of CSS, but that's not necessarily the case with all the settings.

Some of them.

Like the content size setting is maybe two lines.

There are others that maybe correspond to a bunch of logic that includes several lines of CSS.

So there's not a one-to-one correspondence anymore between that and the CSS that's output.

And also, because theme, authors can just say, 'I want this block to have this font size, that color, whatever' they're not actually targeting the markup.

And so that potentially solves that problem.

So advantages of this, it's a lot less, work for theme author because they don't have to build the markup themselves.

In theory, you have less back compat….

Now in practice, maybe you should talk about this later, if anyone's interested, because people do keep creating, style sheets.

It's still allowed to add style sheets to your themes.

And so sometimes people will add their custom CSS logic in there and the, well, what happens is when we do change markup, people do tend to complain bitterly about it.

We have a very passionate community, which is normally a good thing, but sometimes discussions do tend to go on a bit.

the other, the big advantage for us here, I think this is like the major one to focus on, is that we have all control over the CSS specificity because we are outputting the CSS that the themes tell us to ourselves, and this is very important because we are also providing a bunch of tools that allow users to customize their block, their content blocks.

And we need to make sure you know that the platform needs to make sure that when the user customizes their block to have a certain background color that actually takes effect and it's not overridden by some overly specific theme style.

So that's the work that we are doing is that making sure that there's the hierarchy in all of this is respected.

And it also provides more flexibility for end users because now they can customize a whole lot more stuff than they could before.

So on top of choosing a custom theme, end users can also change basically everything on that theme now, which can be a scary idea for theme authors too.

Okay, so downsides.

Yes.

I want, I just want to mention this one, which, I think increasingly this is becoming not a problem because browser support isn't what it used to be, but I am very aware that some people still need to support IE8, if you work for government, you might still be having to support IE8.

And the reality of it is this new theming system, because the platform is writing all the CSS, we decided that we wanted to use cool new stuff like grid and custom properties, and that means that support for IE, not good.

but you can always, so that the old way of building themes has not been deprecated.

It's still in use.

So what happens is you have two parallel, basically we have two parallel theming APIs at the moment, and users can still choose which one they, prefer to use or, but the new one is way cooler, but the old one is still there in case you need it, which you might.

Okay, so now let's look at application themes.

Which are the, other, oh, I still have 10 minutes.

yes.

So application themes are a bit different because obviously you're not going to be writing any markup for them.

you're just going to be doing minor customizations, probably changing colors, maybe a background image, some icons, stuff like that.

And as an example, I want to show you VS code, which is the code editor I use, I bet a bunch of you probably use it too.

It's a, quite a good one.

VS code provides three different, theme types that you can build.

You can build a color theme.

File icon themes and product icon themes, the product icons, other the sort of default VS code UI themes that you see there.

I'm going to look at color themes as an example.

So this is what a color theme in VS code looks like.

And this, part of it is just customizing the colors in the ui.

So you have a slightly different thing for the syntax highlighting it works slightly differently, but for the UI what you have is basically a JSON file.

It's actually JSON-C file, which is JSON with comments, which I find rather neat, although I don't have any comment examples here, but, so what you have is the JSON file.

It has a bunch of, areas of the UI and states that those areas of the UI might be in.

And for each of those you can add a color.

And the way of adding a color is by adding a hex code.

So you need to know the hex code for that color and you add it in.

Fortunately, if you're writing your theme in VS code, it provides you with that little color preview, which is pretty neat.

So this doesn't really tell us anything about how VS code works out where the colors need to go or, what it does in the backend.

It's just here are, the areas that you can customize.

And you can add a hex code for each of these areas.

We can see, because you can actually open dev tools in VS code and you can examine it, which is pretty cool.

And so you can go in there and inspect and see that that's CSS, right?

Those colors are being implemented with CSS custom properties.

So in theory, because VS code is using CSS, they could allow us to to add the colors in as something other than hex codes, because like CSS supports custom color names, well named colors.

I never know how to say it.

Name colors, gold and hot pink and Rebecca Purple.

We all know those, so why can't I just add those color names in there?

they don't allow it, and I think that's actually a very sensible thing to do because if they ever decided to change their implementation and build it in a completely different way, and they did allow you to add CSS color names, they would be stuck with supporting that forever or not.

They would just break things for every theme.

So that's a good thing to do.

And, I guess another way that you can think about it is as, just because you are using a certain technology to build your thing, and that technology has certain affordances, that doesn't mean that you should just expose all of those affordances in your API.

It's good to think primarily about what your users actually need and just provide the basic to allow them to do that, and then maybe those needs will change over time or maybe you'll but users will request the ability to do different things, and you might consider that, but just start simple and don't go, oh, we could do this, so let's just make that happen and see what people do with it, because that'll probably just end in chaos.

Another particular, use case I guess, or, well, I guess this comes under application themes because it's really a user facing thing, your website can be an application and you can provide themes for your users.

Now, the very most common of all use case for this is, dark theme supporting system, dark theme settings, which is great.

I love that.

I use dark theme everywhere, so I'm very thankful when websites think to provide this.

And it's really easy to implement because you have CSS custom properties.

You can define your basic light theme, and then you can just add a media query to target the preferred color scheme of the user.

And if that preferred color scheme is dark, then you change those custom properties to be dark theme ones.

And the interesting thing here is that can also function as an API for third parties to hook into with, in, in the, the logic and tradition of MySpace because anyone can build a browser extension.

And yes, that's, those are the properties being applied in your code.

Anyone can build a browser extension that can target the markup of your browser.

So it's useful when you're building a website to, to always have at the back of your mind that even if you don't want it to, and even if, that's never going to be a concern for you, that markup that you are providing is, can always be an API for someone.

The primary, like the, I think the major use case that I can think of for this is browser extensions that change colors.

this, these can be really great for accessibility.

So I, as I said, I use dark theme everywhere.

When I find an Irritatingly Light website, I usually just go switch on that extension.

That's Dark Reader.

It's an open source extension, so you can actually go in and read the code and see how they've implemented it.

It's on GitHub.

Dark reader.

And so what it does basically like the sort of basic format of how it works is it'll add an inversion filter to your HTML, which will just blanket invert all the colors on the website.

But then you have more custom settings because that doesn't always work for all websites.

It really depends on what kind of colors you have.

So you can customize the settings and there's even a possibility for users, say there's like a, news website that you use all the time.

And annoyingly, dark reader doesn't really work very well with it.

And so you can provide a snippet of codes with some CSS targeting specifically the markup of that website and it will get added to dark reader and they will serve that snippet of CSS whenever you load that page.

That's really cool.

And that is, I think, and I know that, for very good reasons nowadays, a lot of us do that thing where we hash the class names and that has a lot of advantages.

Developer experience, not the least, but also performance.

But a very good use case to provide readable class names is that people can do this thing, they can customize the way that they see your website and, that can, there can be very legitimate and sound accessibility reasons to do that.

So it's a thing to take into account.

If you take anything away from this talk, I want it to be this.

You never know what people are going to do with your stuff.

You can build like the strictest, the Boringest API, and people will find ways to do unpredictable things with it.

So I guess just be prepared.

I don't really have any good advice except that the.

Be prepared, be able to iterate on it quickly.

if, I guess if you don't want surprises, you should just lock everything down as much as possible.

But even then, that can always happen.

And don't forget that, oh, surprises are sometimes good and it's, good to, it's good that to let the unexpected happen because imagine if MySpace had never made that dreadful mistake all those years ago.

I think the Web might be a very different place.

Maybe we would never, like themeing would never have been a thing.

So yeah, just sometimes it's good to just let things happen.

So a few references, there, if you're interested in the WordPress block editor and what we're developing, that's the url for it on GitHub up there, WordPress, Gutenberg, or just contract with me.

It's literally my job to talk about it and not to talk about it most days to code.

But yes, when I'm in a conference, then it's my job to talk about it.

VS code theme blocks.

If if you use VS code and you're interested, go check them out.

Maybe you'll build yourself a theme.

and that, I wanted to link to that Code Academy Post, which is about my space and its coding legacy, because that was the thing that inspired me to talk about it in this talk.

and, yeah, that's it.

I'm on GitHub as tellthemachines.

I'm on Tumblr with my real name.

I know.

Shock horror.

mainly for shit posting purposes.

I'm also on the bird website, which I'm not sure anyone still uses.

and yeah, that's it.

Thanks.