LCM Workshop: Connecting API Platform to Mercure (3 of 4)
Complete demo code available at: https://github.com/LastCallMedia/mercure-api-platform-demo
In this video, 3 of a 4-part series, we show how to connect a simple API Platform app up to Mercure and how to verify that API Platform is publishing correctly to Mercure by using the Mercure demo UI.
Relevant URLs:
https://github.com/dunglas/mercure
https://github.com/api-platform/api-platform
https://jwt.io/
Transcript:
[bright electronic music]
Silas: To connect our API Platform project to our Mercure hub, we’re going to need to first upgrade the API Platform Core version to the master branch, and we’ll have to install the Mercure bundle, Mercure Symfony bundle. So first, I’m going to shell into my composer container, and I’m gonna run a little bit of a complicated command, because I have found that this command often runs out of memory, or always runs out of memory. Not sure why, but, we’re going to run it with this memory limit equals negative one, so no memory limit.
We need to get API Platform/Core master and Mercure, which we had as the Symfony bundle. But first, since this is a master branch, we need to go over to our composer.json file and set it up to allow for dev packages, as master’s considered instable. So I’m gonna run this and this is going to take a little bit of time, so I’ll just pause the video, and we’ll be back in a minute.
Okay so that finished up and now we have the API Platform Core at master, and we also have the Mercure bundle. So, let’s look at the code and see what changes have been made. The docker-compose file just has the stuff that we changed in the last video, .env.dist, which is just the file with the sort of a list of environment variables and their defaults so that you can copy that .env and make your changes, that now has a couple new variables in it to allow configuring how API Platform will connect to Mercure. Composer.json has the two new packages, the lock files have been updated, the bundles.php file has the Mercure bundle added to it, and the yaml files now reference the new environment variables.
We’ll now configure those environment variables to get this working. So we open .env, and the first variable MECURE_PUBLISH_URL needs to point at the Docker container of Mercure. And so, we gave that the name in Docker Compose of Mercure, and the port is just gonna be 80, so we’re not gonna use port 9090 because that’s the port we set up for my local system, and this is instead going to connect directly to the Docker container. This variable’s looking good. For the JWT secret, we need to set up a token with the correct publish permissions for this, and it needs to be encoded using the key that we set up Mercure to use.
So that was set in Docker Compose, I’m gonna copy that right now, for use in a second, and go over to the Mercure page, click create token, that sends me to jwt.io, with this payload data filled in. I’m gonna remove the subscribe targets, because this won’t subscribe to anything. And I’m going to allow it to publish to anything, so I set that to asterisk. I give it the correct key, so that it’s encrypted properly, and it’s ready to use, so, copy that, and paste it into the environment variable here. One potential gotcha here is that you really, you don’t wanna have quotes surrounding this variable, because those quotes will make their way into the environment variable, and nothing will work, and it will be confusing. So that’s set properly, I’m going to quickly… stop my containers, and restart them, so that it’s using the new environment variable configuration. And I’ll just let that run for a second.
Meanwhile, we need to configure an entity to actually send updates to Mercure when changes are made, so when a POST is made or a PUT is made, and we’ll be using this greeting entity, which is the dummy entity that, it’s sort of just a sample entity that comes with API Platform. For our purposes it’ll work, it has a name and an ID.
So, to configure this for Mercure, we just add the Mercure attribute, and set it to true. Now, this will not be targeted at any targets. If you wanna use targets, you could do something like object.user, and if greeting had a user variable on it, which was pointing at a particular user, maybe the user that created the greeting, this would use the ID of that user, and target it at that user. And then you could elsewhere give that user a JWT token, which allows it to listen to that target, and that information would be protected, and only the owning user would be able to get updates for its objects. But, we’re not worried about that, we just wanna keep it simple, and we set it to true, which turns it on. So that should be good.
We’ll open up the UI for API Platform, at “localhost:8080,” and this will allow us to run a POST to create a new greeting. I’m just gonna configure this quickly, “hello world.” And I’m not going to create it yet. First, I want to set up the demo client to listen. And I’m going to remove the publish permission, but I’m not gonna worry about subscriptions because it’s not going to be listening to any particular target. So this token’s good, paste that into the demo, click discover to set up the cookies, and here we need to make sure we’re listening to the right topic. We need to set this to 8080, which is the port that API Platform is using, and we need to set it to listen to greetings, which is the name of the entity, and then we’re going to, instead of just putting a numerical ID here, we’re gonna put in ID like this, which will be a placeholder for the ID, and so we’ll hear updates for any greeting that’s created or updated. Click subscribe.
Now, when we post this, in addition to creating the new entity and saving it to the Postgres database, it should also send an update to Mercure, and our subscriber in the other tab should show an update. And it worked! So everything’s working, it’s looking good. Obviously this is not something that you’re gonna show your boss or, you know, your friends and family, but everything seems to be working and in the next video we’ll create a quick React app, which will, it’s not gonna look too pretty, but it will at least show this in a more functional way. And we’ll show it with two windows side by side, with one making the update, and the other receiving it instantly. So, that’ll be the next video, and I’ll see you soon.
[bright electronic music]
