The Acquia Cloud API is a web service and CLI that allows developers to build powerful tools, automate repetitive tasks, and create custom development and testing workflows for sites on the Acquia Cloud platform. Released two years ago, our customers and partners have been building amazing things on Acquia Cloud API and we figured it was time to share some of them. We hope this will reveal the potential of the Acquia Cloud API and show some examples of what it can do for you.
There are three fundamental components to Cloud API:
- A RESTful web interface that allows direct control of Acquia Cloud sites.
- The Acquia Cloud API is the core of the whole system and functions as a RESTful web service. It enables developers the ability to build the tools they actually need if leveraging Acquia’s UI isn’t part of their workflow. This could be as extreme as building a mobile application for Acquia Cloud’s workflow, or as simple as writing a utility to purge your varnish cache.
- A full featured CLI based on drush.
- The Acquia Cloud CLI is a set of drush commands that function as a wrapper around the Acquia Cloud API. It provides an easy way to get started and begin experimenting and can give you something you can easily dissect in order to formulate a more custom approach to interacting with the REST API.
- Custom script execution through Cloud Hooks.
- Cloud Hooks allow you to automate almost anything as part of your workflow actions between Acquia Cloud environments such as Dev, Stage and Prod. A great example would be sanitizing all your user data by scrubbing passwords and emails before moving data from production to development.
As outlined above, there are 3 categories of solutions that are commonly built on top of Acquia Cloud API:
- Power Tools
- Dev Desktop
- Task Automation
- Anonymizing user data in the Database in the development environment
- Custom Dev/Test Workflows
- Github/Jenkins integrations
- General Continuous Integration
With an open API upon which to build, Acquia Cloud API enables the creation of powerful tools to manage your sites. Acquia has done this with the second major release of Acquia Dev Desktop, a local xAMP development stack, embedding the ability to bi-directionally manage deployment of your code, database and files to the appropriate environment in Acquia Cloud.
Cloud Hooks are a mechanism, that has been written about previously by a number of our partners. If you’d like a great overview of the basics of Cloud Hooks, I’d heavily suggest James Rutherford’s introduction to the topic over at MediaCurrent.
I mentioned earlier the example of sanitizing your database before moving it to the development environment so that working in your development environment doesn’t inadvertently email all your site’s users. The Cloud Hook setup for this is as follows:
hooks/dev/post-db-copy hooks/test/post-db-copy site="$1" target_env="$2" db_name="$3" source_env="$4" drush @$site.$target_env sql-san -y
There are dozens of other easy examples to cite here, but I won’t do so because Richard Jones of i-KOS did a brilliant job of that already.
Custom development and testing workflows are a big part of being able to effectively maintain any site, and the Acquia Cloud API was designed to facilitate addressing exactly this problem space. Let’s look at both direct usage of Acquia Cloud API as well as some Continuous Integration solutions.
As developers, many of us are very familiar with GitHub, and a lot of developers and corporations choose to keep their code on github. With Acquia Cloud providing its own git repositories, management of this distributed code base becomes a big question, and Acquia Cloud API is being leveraged to answer that question. In order to accomplish this, Continuous Integration becomes an important point in the discussion. Whether you’re using Jenkins or some other tool, most CI approaches are pretty analogous across solutions. Jenkins is a good starting point since there are plugins for GitHub integration, but no matter what you choose to use, this outline should be useful.
I’ve seen two basic approaches to github integration. One includes a lot of tagging and the other leverages Drush make. Your approach is likely to vary based upon how you’ve setup your solution. If you track the full code base for a site, the tagging may be a better solution for you, and if you’re developing from an install profile and rebuilding that distribution as part of your workflow, the Drush make option is likely to resonate with you.
In this approach, Acquia’s git repository is treated as disposable. GitHub’s repositories are treated as the canonical source for all code. Commits to github result in a forced push to Acquia’s repositories and tags are created on an ad hoc basis for deploying particular commits into Acquia’s repositories. This is done through a custom event system that can capture things like “new code on master” and then generate a tag and push the code to Acquia. This allows the deployment of specific commits at a specific time. Most of this work is going to fall into the category of “Continuous Integration”, but the final step involves selecting which tag will be running in a given environment and that can be done via this api call. If you’re leveraging a single git repository for your entire site, this or something like this is likely to be a really great solution for you.
I’ve been a long time fan of Drush make. It has its flaws, no doubt, but for anyone wanting to manage features independently in their own git repositories, it’s definitely the go to solution. In this setup we leverage a CI server in order to rebuild and push our distribution after any commits to a feature repository. Once the code is pushed to Acquia’s system a polling service can check the associated task and when complete pull a copy of the live database and files into the dev environment and then login to the server via ssh, and perform the appropriate drush calls (cc/fra/dbup/etc) as necessary.
In both of these scenarios you’ll want to purge the varnish cache when you’ve finished.
Acquia Cloud API is very flexible, and can support many different approaches. Hopefully these examples give you a good place to start in building a solution specific to your needs. Others have written about integrating github and Acquia Cloud before, if you’d like something a bit more in depth, check out Nick Schuch’s article on PreviousNext. Nick covers a few other things for good measure in this article, so you might find a few more time saving tips.
A critical component to all these git workflows is the continuous integration aspect. CI has become integral to testing and development and ensuring sites continue to work through feature deployment and module updates. So many solutions revolve around this feature of the development cycle that Acquia is committing to tighter integration specifically with Jenkins and has recently made our Jenkins plugin for Cloud API publicly available. This is still in development and currently has the facility to deploy code, but more features are in development and contributions are definitely welcome.
In short, a number of our customers and partners have been building great things on top of Cloud API for a long time, and we’d like to see more people doing the same. If you have a site on our platform and you’ve not leveraged these sorts of tools yet, this article will give you a good starting point. Sign up for Acquia Cloud Free if you’d like to begin working with these tools today and if you need some help doing more, feel free to reach out to me directly and I’ll happily point you in the right direction.
Acquia Cloud API: Documentation
Cloud Hooks: Documentation
PreviousNext: Automating Drupal Migration to Acquia Managed Cloud
mediacurrent: Using Cloud Hooks on Acquia Cloud Hosting
i-KOS: 10 Ways Acquia Cloud Hooks can help you sleep at night
Github: Jenkins plugin for Cloud API
I’m Kris Vanderwater, Drupal developer and Acquia's Developer Evangelist. My job is to help you – the developer – get the most out of Drupal and Acquia’s products and services. If you ever have questions, comments, or concerns, reach out to me any time. I've included some ways to contact me below.