API Alpha Events Rollout

, by

The goal of the new API has never been to rewrite the same software with new technology. We intend to come out of this project with a new application that accomplishes the same legacy tasks, but has been designed from 13 years of practical experience.

Notwithstanding that hindsight, one of the biggest challenges we have faced while developing the API v4 is re-imagining Linode’s systems while maintaining compatibility with the existing infrastructure.

It isn’t always easy. In fact, during the past month we have battled one of the biggest specters in this space - database performance. This battle took place entirely behind the scenes, which is why we haven’t rolled out any iterations in a while.

Today, however, we can and do. On our way to re-imagining Linode, we have created something entirely new that we think you’ll find valuable.

Today, we proudly roll out “Events.”

Introducing Events

New from Linode, an Event is something that has happened - or in limited cases, will happen - that not only involves your Linodes, but also your account and other things you care about.

An Event could be “Create a Linode” or “Shutdown a Linode.” It could be “Your Ticket has been Updated” or “New Post on the Linode Blog.” Events can be seen and read, and may have other objects associated with them - either in the API or elsewhere in the Linode system.

Corresponding to the new design, Events are present in the Linode API, and all facilities involving them are available to third-party developers as well. This means that you could easily integrate Linode Event updates to your i3 bar, for example. For now the alpha is getting Linode-related Events only, but we will be expanding their rollout in the coming weeks.

Events are in the account group, and can be accessed like so:

  • GET /account/events - returns a paginated list of events for your user
  • GET /account/events/:id - returns one event with the given id, or 404s
  • POST /account/events/:id/seen - marks the event at id and all events before it as seen
  • POST /account/events/:id/read - marks the event at id as read

Notice that you can’t POST to /account/events? This is a read-only collection that is populated while you do other things. For instance, POSTing to /linode/instances/123/boot will create an Event ‘Booting Linode linode123.’ For more information on events, see the event documentation.

Busy Boxes

To support Events, and to simplify Linode systems overall, Linodes will now only accept actions when they are not busy. For instance, while your Linode deploys, you won’t be able to ask it to reset its root password until it’s done.

The only exception to this prohibition is booting - you can always ask a Linode to boot when it has completed whatever task it’s doing. This may sound like a big change, but we believe it will have little impact on the normal use of our systems, and will save the majority of our users from confusion and complexity.

Other Changes

In addition to the above, we’ve tweaked a few attributes of the Linode and Backup objects:

  • Linode objects now return only the address for IPv4 and IPv6. If you need more information, call out to /linode/instances/:id/ips
  • Linode objects now list their hypervisor (in the alpha, only KVM is available).
  • Backup objects now include their availability - if unavailable, they cannot be restored.
  • To reset RDNS on an IP, PUT { "rdns": null } to /linode/instances/:id/ips/:ipid

Let Us Know What You Think

As always, thank you for your continued support and feedback. In addition to the usual channels - #linode-next on oftc and on github - you can now send us your feedback directly through the API. Just POST your thoughts to https://api.alpha.linode.com/v4/feedback (requires a token) with a body like {"message": "you guys rock!"}.