The year is 2020. WordPress powers over 35% of the web now. The REST API has been in WordPress core for a few years; the year after the REST API was merged into core, WordPress gained nearly 5% marketshare.
Almost all WordPress sites use the REST API in some form or another, and an estimated 15% of all native apps use WordPress purely as a backend. 80% of the top 100 news websites run WordPress with front-ends powered by the REST API. A dozen popular hosted website platforms have custom admins or front-end editors that use the API.
All of the “we should get to this eventually” items have actually been done, unbelievably, and we’ve entered the Golden Age of the WordPress REST API.
Many people all across the web are using the API. Here are some of their stories.
Meet Jack. He’s an avid follower of various different YouTube channels, some of which are 15 years old now. YouTube is still one of the biggest media companies, especially since the number of hamsterkitten videos has skyrocketed since the animal was first crossbred in 2018. Jack runs a fan site that has a few thousand hits a day, which is not a huge site, but roughly in the middle of the long-tail of WordPress sites. He hopes to grow it further though.
Jack’s just seen a great new video pop up on the new video feed. After having watched it (and taken extensive notes), he decides to share it with his followers on his WordPress site. Underneath the video, he taps on the “Share on WordPress” link.
Due to the decentralized nature of WordPress sites, YouTube can’t register with Jack’s site directly without a lot of effort. Instead, YouTube has registered with WordPress.org as a client beforehand (just like a normal centralized service). WordPress.org acts as a middleman between centralized services and clients, and the millions of WordPress installs out there on the ‘net.
YouTube sends Jack off to WordPress.org to create a post. WordPress.org checks and finds that YouTube is a registered client, and they haven’t been blacklisted or had their tokens revoked. Usually, WordPress.org would ask Jack to enter his site, but Jack’s done this before, so his browser has remembered the sites he’s entered previously. He picks his site from the list (hamsterkitten.com).
In the background, WordPress.org asks hamsterkitten.com to issue credentials for YouTube, and tells them how to talk to each other directly. (These are OAuth 1.0a credentials, sent over insecure HTTP, since Jack hasn’t gotten around to setting up his free SSL certificate yet. One of these days…)
hamsterkitten.com checks and finds that Jack has already done this before, so YouTube already has a set of credentials ready to go. He’s also already approved linking his YouTube account to his user account on his site, so he doesn’t need to approve his account manually. It passes the credentials back to YouTube, and YouTube sends a request back with the video data.
Jack doesn’t see any of these happening in the background. His browser sends him off to hamsterkitten.com’s WordPress admin, where the video is pre-entered into his editor. He adds some witty comments and publishes the post. YouTube then automatically shares the video on his YouTube account as well for him, and automatically sends a notification to his YouTube followers to keep them up-to-date.
Jack’s post turns out to be enormously popular, and starts a new wave of hamsterkitten fandom, earning him millions from the movie tie-ins and branding promotions.
Despite the decentralised nature of WordPress sites, YouTube was able to work seamlessly with Jack’s site. It used WordPress.org as a middleman to bridge the gap, without sharing any private data with WordPress.org. It did this all while keeping the connection secure over insecure HTTP.
On the other side of the world, Jill’s a mobile developer working on her first app. She’s heard all about this hamsterkitten craze, and has seen a business opportunity in creating a mobile app to post photos of them wherever you are in the world.
Jill wants to be able to post to any WordPress site, but can’t go around and register her app on every site. Instead, she goes and registers her app on WordPress.org, which gives her access to every site with an extra step or two.
While waiting for her app request to be approved, she sets up a new WordPress test site, which humorously uses the domain wassupwitd.at. (She knows that domain hacks are so early 2000s, but she still likes them.) She registers her client manually on her test site, which issues her with a client key and secret. She starts writing her client using these directly.
Her client is a pretty basic wrapper around the Camera app that lets you upload directly to your site, but with some tricks up its sleeve. She adds some special functionality for sites with WooCommerce or EDD (which combined now represent 80% of online e-commerce), letting people create new products to sell their photos on their site, all from her app. She lets people upload multiple hamsterkitten photos at once, with support for creating sliders directly in the app.
After not too long, her app request gets approved, and she’s given a key and secret to use with WordPress.org. She switches her app over to using those instead. Her app first talks to WordPress.org using this key and secret (hardcoded into the app), which then issues the app credentials for each site it accesses (stored inside the app).
She wipes her test site and reinstalls it, now running stock WordPress with no real data in it. She hits the “Connect” button in her app, which sends her off to WordPress.org. WordPress.org hasn’t seen Jill before, so it asks her to enter her site’s address. She enters “wassupwitd.at” (laughing again to herself), then hits the continue button.
WordPress.org hasn’t seen this site before, so it runs the auto-discovery process internally to find the site. It double-checks the authentication available there, then after making sure the site has the necessary bits enabled, asks the site to create client credentials for the app. It also redirects Jill off to the site.
The site double-checks the validity of the client by sending a request to WordPress.org in the background, then creates a new client key and secret for the app. It passes these back to the app, and the two begin communicating directly.
Jill hasn’t linked her app to this new test site before, so she sees the classic OAuth “Authorize This App” page on her site. After logging into her test site, she links the account to her app, and all is well with the world.
Satisfied that the linking process is working for her, she gets ready to launch her app. She fills out her app details on WordPress.org to appear in the app directory, complete with a funky logo.
However, disaster strikes! It turns out she made the mistake of posting her client credentials on a public GitHub repository. After reassurances from her colleagues and pets that everyone has done this at least once, she goes about setting it right.
Her first step is to log on to WordPress.org and revoke her client key and secret from there. Internally, this does a few things. The first and main thing is that it stops clients from linking with new sites, since WordPress.org stops asking sites to issue new credentials when requested. This immediately stops the bleeding, but it doesn’t clean up any mess that’s already there.
The next thing that happens is that WordPress.org adds the client key to the list of revoked clients. This is pulled down by sites automatically as part of their autoupdate check every day, and those sites revoke any credentials for the clients already on the site. This will make Jill’s site automatically revoke the previously issued client token in the next day, ensuring that it’s safe even if it’s already linked.
Luckily for Jill, her app was still in testing, so there wasn’t a huge impact. If there was though, the WordPress security team could have assessed the issue to see how urgent it was. In urgent cases, they could check which sites have linked with the client previously and ping them via a backchannel to have them check the revocation list immediately instead. This would ensure maximum security for sites which are known to be affected.
Now that she’s revoked her credentials and reissued new ones, she steadies herself, and launches the app. As it turns out, this app is exactly what the hamsterkitten community needed, and it surges to the top of the various app stores in mere hours. Jill goes to sleep that night confident that if any real security issues do pop up, she’s well-equipped to handle them, and the WordPress security team has her back.