Upgrade or Downgrade API Maker From Your Pipeline With One Call

The one step left by hand

0:00 Engine webhooks. One call from your pipeline upgrades or downgrades API Maker itself, on every server. Think of how your code reaches production today. A pipeline tests it, builds it and ships it, with nobody watching. But the engine underneath is often the one step still done by hand : somebody signs in to each environment, picks a version, and waits. With many environments, that step comes late, or it is skipped.

0:30 An engine webhook puts it in the pipeline. One call with a version, every server installs it, and a server which can not start on it goes back on its own. So let us build it, step by step : making a webhook, deciding who may call it, why it stays out of git, a dry run, the real upgrade, and what a refused call looks like.

Making a webhook

0:53 Webhooks live with the other ways to change the engine. On the dashboard, under Operations, Upgrade Engine. At the top, the two ways you may know already : a bundle, or a version of npm. Below them, the third one : upgrade or downgrade by API. There is no webhook yet, and three steps say what one does. An address which can replace your engine has to be protected, so a webhook is made of three values.

1:22 New webhook. API Maker fills them in with random ones : keep them, or type your own. First a name, so that you know later who calls it. The hook URL is the last part of the address. The access token says which webhook is called. And the secret proves that the caller may use it. The secret deserves a moment, because you only see it once. Show it, and copy it now : once it is saved, it is kept encrypted, and it can only be replaced, never read back.

1:55 The final URL is what your pipeline calls, with a POST.

Who may call it

2:00 Next, you decide what a call may do. Allow downgrades is what lets a pipeline go back to an older version. Turn it off, and an older version is refused. Active stops every call at once, without removing anything. And when you list addresses, only those callers are answered. So we add the address of our pipeline, and we keep it. Save.

How to call it

2:25 Now, how does the pipeline call it? The row answers at a glance : who may call, whether it downgrades, and its last call. Open it, and the page writes the call for you, with the address and the token filled in. Only the secret is left for you to put in. A second call asks how it goes. And the whole step is ready to paste in a pipeline.

Out of git

2:49 You may wonder why this is not in your repository, since almost everything else is. A repository travels : to other environments, to every developer, to whoever can read it. An address which can replace the engine should not travel with it. So a webhook is never part of a commit, a pull or a push. Each installation makes its own, and it stays there.

A dry run

3:13 Before the first real call, you want to know it would work, without any risk. That is what dry run is for. API Maker checks all of it : the credentials, the address, the version, and which way it goes. Then it says what it would do, and it installs nothing.

The real call

3:31 Now the real one. The same call, without dry run. It answers at once, with the name of the run, because a deployment takes longer than most proxies wait. From there, a second call asks how it goes. Running, while the servers download and install it. Restarting, until each of them answers on the new version. A call may find nobody for a moment, so ask again. And done. And what if the new version does not start?

4:02 Underneath, each server does what the page does. It downloads the package of its own machine, and checks it. It unpacks it next to the running version. It checks that the program starts. The new version takes its place. And if it can not start, the server goes back to the version it ran. The status then says failed, and why.

Refused calls

4:25 An address on the internet gets calls you did not plan, so you want to see them. Every call is listed, refused ones too, with the address it came from. Our dry run. An older version, while downgrades are off. A caller who is not on the list. And a wrong secret. Each says why it was refused, and nothing was installed.

Good habits

4:48 A few good habits. Keep the secret in the secrets of your pipeline, never in its code. Make one webhook for each pipeline, so that you can switch one off alone. List the addresses which may call it. And on production, keep downgrades off unless going back is the job of that pipeline.

Recap

5:08 To sum up. A webhook is an address, a token and a secret, kept on your server and out of git. A call with a version is answered at once. A second call says how it goes. A server which can not start goes back on its own. And every call is listed, refused ones too. Next, how to upgrade from the page itself. API Maker. Build faster, spend smarter, deliver better.