Monthly Archives: March 2018

Dev Channel Update for Chrome OS

The Dev channel has been updated to 67.0.3381.0 (Platform version: 10525.0.0) for most Chrome OS devices. This build contains a number of bug fixes, security updates and feature enhancements. A list of changes can be found here.  

If you find new issues, please let us know by visiting our forum or filing a bug. Interested in switching channels? Find out how. You can submit feedback using ‘Report an issue...’ in the Chrome menu (3 vertical dots in the upper right corner of the browser). 

Kevin Bleicher
Google Chrome

Twenty three third-party applications added to the G Suite pre-integrated SAML apps catalog

With Single Sign-On (SSO), users can access all of their enterprise cloud applications—including the Admin console for admins—after signing in just once. Google supports the two most popular enterprise SSO standards, OpenID Connect and SAML, and there are many applications with pre-integrated SSO support in our third-party apps catalog already.

Building on other recent launches (February 27th, March 12th), we’re adding SAML integration for 23 additional applications:

  • Adaptive Insights 
  • Buildkite 
  • Citrix ShareFile 
  • CrashPlan 
  • Fuze 
  • HappyFox 
  • Huddle 
  • Image Relay 
  • itsLearning 
  • Jobvite 
  • Klipfolio 
  • Mimecast 
  • Mozy 
  • Enterprise 
  • Periscope Data 
  • Pipedrive 
  • Pritunl 
  • Qubole 
  • Runscope 
  • Saba 
  • Solium Shareworks 
  • Spotinst 
  • VictorOps 
  • Zuora 

You can find our full list of pre-integrated applications, as well as instructions for installing them, in the Help Center.

Note that apart from the pre-integrated SAML applications, G Suite also supports installing “Custom SAML Applications,” which means that admins can install any third-party application that supports SAML. The advantage of a pre-integrated app is that the installation is much easier. You can learn more about installing Custom SAML Applications in this Help Center article.

Launch Details 
Release track:
Launching to both Rapid Release and Scheduled Release

Available to all G Suite editions

Rollout pace: 
Gradual rollout (up to 15 days for feature visibility)

Admins only

Admin action suggested/FYI

More Information 
Help Center: Using SAML to set up federated SSO

Launch release calendar
Launch detail categories
Get these product update alerts by email
Subscribe to the RSS feed of these updates

Search, with social: Unify your cross-channel marketing for better business results

Consumers engage with your brand across many channels, from search to display to social. However, only 17% of advertisers look at performance across these channels.1 And while search advertising will continue to make up the majority of digital ad spend this year, spending on social ads is estimated to grow. That’s why we’ve expanded DoubleClick Search’s best-in-class cross-channel reporting and optimization to include social ads. Key features include:

Automated click and view tracking

We’ve partnered with social marketing platforms, including 4C Insights and, to make integration simple. Once you connect your account, DoubleClick’s view and click trackers are automatically applied. You’ll be able to see your Floodlight-based conversion metrics, including visits, actions, transactions and revenue in your social reports. In the coming weeks, we’ll be expanding support to include Brand Networks and Sprinklr.
Connect to top paid social marketing platforms
If you’re not using a social marketing platform, you can use tracking sheets to see your social ads activity directly in DoubleClick Search.
“DoubleClick Search streamlined the process of connecting our DoubleClick click and view trackers to our social campaigns. We’ve saved upwards of 6+ hours a month in trafficking, while still being able to leverage attribution insights in DoubleClick Campaign Manager.”
— Andi Brosseuk, Team Lead, iProspect Canada

Unified reporting across channels

See your search, social and display data all in one place. With a connected social account, your clicks, conversions, impressions and cross-channel remarketing metrics are captured together with your other channels.

Using different tracking tags across channels often results in splintered and duplicated data. To ensure you don’t overvalue clicks or channels, DoubleClick Floodlight tags deduplicate conversions across search, display and social. You can also report on assisted conversions, which tells you the number of conversions that were assisted by a particular keyword or ad.
See your search, display and social data together

Unified cross-channel attribution

Assign credit to the right customer interactions across channels by using a single attribution model. Then use Smart Bidding to automatically set bids informed by your cross-channel attribution model for even better performance.

You can also include social data in your DoubleClick Campaign Manager path-to-conversion reports to understand the role your social ads play in your customers’ path to purchase. For example, if you see that most of your sales happen after multiple clicks on your social ads, there might be an opportunity to refine your social ad content.

Cross-channel remarketing

Drive more conversions by creating an audience in one channel, and reaching them on another. For example, reach qualified shoppers on with an engaging search ad after they’ve clicked on an awareness-building social ad. You can re-engage these social audiences on both search and display.
“As an agency, we’re excited to integrate our social campaigns into DoubleClick Search. The ability to share remarketing lists across channels has not only improved our performance, but also enabled our cross-channel teams to work more closely together. We’re now also able to see more of the conversion path in DoubleClick Search, including the addition of social conversions into our Data Driven Attribution models.”
–Beth Williams, Search Platforms Lead, Merkle Periscopix
Learn more about integrating your paid social campaigns in the DoubleClick Search Help Center.

Posted by Sriram Parameswar
Product Manager, DoubleClick Search

1 Source: Advertiser Perceptions/Google, Measurement Survey, U.S., September 2017

New ways to read more with audiobooks from Google Play

Two months ago we launched audiobooks from Google Play to help you fit more books into your life. Today we have a few updates to make it even easier to enjoy a great book, whether you like to listen on the go with your phone or at home with the Google Assistant on Google Home.

  • Never lose your place with Smart Resume.Interruptions happen all the time, and sometimes you need to pause your audiobook in the middle of a sentence or word because your mom calls or maps tells you to turn in 200 feet. When the book picks back up, you have no idea what’s going on. Smart Resume for audiobooks will intelligently rewind you to the beginning of the word or sentence when you pick up your audiobook again, so you’ll be able to jump right back into where you left off.
  • Revisit your favorite moments with Bookmarks.Now you can save all of your favorite moments with Bookmarks in the Google Play Books app. While listening on Android or iOS device, just tap the bookmark icon to save this spot and revisit your favorite quote anytime.
  • Fit in more reading time with routines on the Google Assistant.Every morning you may type in your work address to Google Maps to see traffic, check your appointments in Google Calendar, and fire up an audiobook for your drive. You can do this all in one step, hands free with the Google Assistant’s support for Routines. In the Google Home app, add audiobooks to your routine. Once added, just say “Ok Google, tell me about my day” for an easy transition into your morning—and your book. 
  • Speed it up—or slow it way down—with greater speed controls.Sometimes you just just can’t wait to figure out whodunnit. Now, you can listen to audiobooks at 3x speed to get through your book even faster, or slow books down to 0.5x in order to really savor the language. The pace is up to you.
  • Share with Family Library in 13 new countries.With Family Library, you can share audiobooks and ebooks with up to five family members for free (depending on the book). Shared books can then be read on Android, iOS and the web. Today, we’re rolling this out to even more families in 13 new countries, including Belgium, Germany, Italy, Netherlands, Norway, Poland, Russia, Spain, Switzerland, Chile, Mexico, Japan (audiobooks only) and South Africa.

These new features are rolling out starting today on Android, iOS, and on devices with the Google Assistant. Time to get back to my book.

AdWords and DFP client library for Java will soon require Java 8+

Starting on July 1, 2018, all releases of the Google Ads API Client Library for Java will only be compatible with Java 8 (1.8) and higher.

Why this change is happening
The primary reasons for this change are:
Next steps
If you are using Java 8 or higher, no action is required.

If you are still using Java 7, you'll have to migrate your runtime to Java 8 or higher. Check out the Java 8 adoption guide from Oracle to get started.

Still have questions? Feel free to file an issue on the library's issues page or contact us via our Google+ page.

Is Optimize set up correctly on your site? Let us double-check for you.

Google Optimize helps businesses determine which website experiences work best for their customers. With easy-to-use A/B testing capabilities, marketers can use Optimize to create and launch a test in minutes — and manage the entire process on their own.

A/B testing with tools like Optimize drives results. In a recent survey, 72% of marketers found A/B testing to be a highly valuable method for improving conversion rates.

But we’ve heard from businesses that while testing in Optimize is easy, setting it up could be easier. 

Good news: We’re introducing a new feature that helps make sure Optimize is set up and working the way it’s supposed to.

Let Optimize double-check your code 

With Installation Diagnostics, Optimize will automatically alert and advise you on potential issues with your Optimize code each time you create a test. At a glance, you’ll see if your Optimize setup is correct and if you’re ready to run a test.

Let’s say you create a new page on your site but forget to add the Optimize code. Later, when you are creating a test for that page, Optimize will tell you that the necessary code isn’t installed. You’ll have the opportunity to fix the issue and then launch your test. Moving forward, you can be confident that your test results won’t be disrupted by an incorrect setup.

Optimize will alert you about other issues too - including if Google Analytics code isn’t installed on a page, or if an old version of Analytics code is installed. Then you can make changes to ensure you’ll be able to measure the performance of your experiment. Learn more.

Try it yourself 

Today’s top businesses are testing their way to success. They’re valuing data over opinions. They’re constantly learning — even from failures and mistakes. And they’re using their findings to improve the customer experience.

Whether your business is big, small, or somewhere in between, you can follow their lead. Try Optimize now and get ready to gain deep insights about your customers so you can enhance their web experiences like never before.

We’ve been busy! 20+ Google Cloud security announcements from March

As Urs said last week, security is one of the biggest issues of our time, and with the cloud, we are able to tackle it together. At Google Cloud, we’re always working to help organizations keep up with evolving threats, protect their sensitive data, and empower innovation—all while giving them control and visibility. That’s why over the past several days we’ve announced a broad range of security products and enhancements. With so much to share, we thought it would be helpful to put all the news in one handy location.

Here’s a recap of our security announcements in March.

Chrome Enterprise

1. New enterprise mobility management (EMM) partnerships

We announced four new partnerships with EMM providers to help IT admins manage and implement security policies across their full fleet of devices from a single place. Cisco Meraki, Citrix XenMobile, IBM MaaS360 with Watson, and ManageEngine Mobile Device Manager Plus now support Chrome Enterprise.

2. Chrome OS Active Directory enhancements

Building on our initial integration with Active Directory last August, we’ve added a number of enhancements to help admins manage Chrome OS alongside legacy infrastructure. These include the ability to authenticate to Kerberos and NTLMv2 endpoints on local networks directly from Chrome OS, support for common enterprise Active Directory setups like multiple domain scenarios, and improved existing certificate enrollment flows.

3. Expanded management capabilities in Chrome Browser and Chrome OS

Chrome Enterprise lets admins fine tune more than 200 security policies and grant secure, authorized employee access to online resources. This month, we added even more controls, including per-permission extension blacklisting, disabled sign-ins, and device-wide certificates.

Cloud Identity

4. Cloud Identity

Cloud Identity is a new, standalone Identity as a Service (IDaaS) solution that offers premium features such as account security, application management and device management in one place. With Cloud Identity, employees get simple, secure access to their business-critical apps and devices, while administrators get the tools they need to manage it all in one integrated console.

Google Cloud Platform

5. Access Transparency

Trust is paramount when choosing a cloud provider, and we want to be as open and transparent as possible. Access Transparency gives you near real-time logs when Google Cloud Platform administrators access your content, offering an audit trail of actions taken by Google engineers and support whenever they interact with your content on GCP.

6. Cloud Armor

Cloud Armor, our new Distributed Denial of Service (DDoS) and application defense service, is based on the same technologies and global infrastructure that we use to protect services like Search, Gmail and YouTube. Global HTTP(S) load balancing provides built-in defense against infrastructure DDoS attacks. Cloud Armor works in conjunction with global HTTP(S) load balancing and enables you to customize defenses for your internet-facing applications. Its capabilities include IP blacklisting/whitelisting, geo-based access control, custom rules via a rules language and defense against application-aware attacks like SQL Injection.

7. Cloud Security Command Center (alpha)

The new Cloud Security Command Center (Cloud SCC) is a security and data risk platform that lets you view, analyze, and monitor an inventory of your cloud assets, scan storage systems for sensitive data, detect common web vulnerabilities and review access rights to your critical resources—all from a single, centralized dashboard. Detect threats and suspicious activity with Google anomaly detection as well as security partners such as Cloudflare, CrowdStrike, Dome9, Palo Alto Networks, Qualys and RedLock.

8. The Cloud Data Loss Prevention (DLP) API

Discover, classify and redact sensitive data at rest and in real-time with the DLP API, now generally available. And because it’s an API, you can use it on virtually any data source or business application, whether it’s on GCP services like Cloud Storage or BigQuery, a third-party cloud, or in your on-premises data center.

9. FedRAMP Authorization

GCP, and Google’s underlying common infrastructure, have received the FedRAMP Rev. 4 Provisional Authorization to Operate (P-ATO) at the Moderate Impact level from the FedRAMP Joint Authorization Board (JAB). Now, both G Suite and GCP have FedRAMP Moderate authorizations. Agencies and federal contractors can request access to our FedRAMP package by submitting a FedRAMP Package Access Request Form.

10. VPC Service Controls (alpha)

Currently in alpha, VPC Service Controls help enterprises keep their sensitive data private while using GCP’s fully managed storage and data processing capabilities. VPC Service Controls create a security perimeter around data stored in API-based GCP services such as Cloud Storage, BigQuery and Bigtable. This helps mitigate data exfiltration risks stemming from stolen identities, IAM policy misconfigurations, malicious insiders and compromised virtual machines.

G Suite

11. New advanced anti-phishing capabilities

Updated phishing security controls can be configured to automatically switch on the latest Google-recommended defenses. New default-on protections can:

  • Automatically flag emails from untrusted senders that have encrypted attachments or embedded scripts.

  • Warn against email that tries to spoof employee names or that comes from a domain that looks similar to your own domain.

  • Offer enhanced protections against spear phishing attacks by flagging unauthenticated email.

  • Scan images for phishing indicators and expand shortened URLs to uncover malicious links.

12. Default-on mobile management

Basic device management is automatically enabled for your mobile devices that access G Suite. Employees won’t need to install profiles on iOS and Android devices, and admins get added security management controls including the ability to enforce pass codes, erase confidential data, and see which devices access corporate data.

13. New additions to the security center for G Suite

We introduced the security center for G Suite earlier this year. Security center brings together security analytics, actionable insights and best practice recommendations from Google to help you protect your organization, data and users. Last week we introduced new additions, including:

  • New security charts to show OAuth activity and Business Email Compromise (BEC) scam threats specifically focused on phishing emails that may not have links.

  • New mobile management charts to help IT admins examine activity analytics and detect when devices have been hijacked, rooted or jailbroken.

  • Ways to reorganize the dashboard to focus on what is most important to your organization.

  • Ways to analyze your organization’s security health and get custom advice on security key deployment and protection against phishing scams.

14. Built-in protections and controls for Team Drives

New enhancements to Team Drives provide additional security controls, including the ability to limit file access privileges and add IRM controls to prevent users from printing, downloading and copying files. These new security features will roll out in the coming weeks.


15-25. New and expanded security partnerships

We announced several new security partnerships, including:

  • Dome9, which has developed a compliance test suite for the Payment Card Industry Data Security Standard (PCI DSS) in the Dome9 Compliance Engine.

  • Rackspace Managed Security, which provides businesses with fully managed security on top of GCP.

  • RedLock’s Cloud 360 Platform, a cloud threat defense security and compliance solution that provides additional visibility and control for Google Cloud environments.

As we said last week, we believe a more secure business landscape is better for everyone, and we’re committed to finding new ways to help businesses be more secure. For more information, check out our security webpage.

Related Article

Security in the cloud

Security is one of the biggest issues of our time. Countless companies and governments have lost data because of security incidents. And ...

Read Article

Related Article

New ways to secure businesses in the cloud

Today we announce more than 20 enhancements aimed to deepen and expand the control businesses have over their security environment. These...

Read Article

Exploring container security: An overview

Containers are increasingly being used to deploy applications, and with good reason, given their portability, simple scalability and lower management burden. However, the security of containerized applications is still not well understood. How does container security differ from that of traditional VMs? How can we use the features of container management platforms to improve security?

This is the first in a series of blog posts that will cover container security on Google Cloud Platform (GCP), and how we help you secure your containers running in Google Kubernetes Engine. The posts in the series will cover the following topics:
  • Container networking security 
  • New security features in Kubernetes Engine 1.10
  • Image security The container software supply chain 
  • Container runtime security 
  • Multitenancy 
Container security is a huge topic. To kick off the the series, here’s an overview of container security and how we think about it at Google.

At Google, we divide container security into three main areas:
  1. Infrastructure security, i.e., does the platform provide the necessary container security features? This is how you use Kubernetes security features to protect your identities, secrets, and network; and how Kubernetes Engine uses native GCP functionality, like IAM, audit logging and networking, to bring the best of Google security to your workloads. 
  2. Software supply chain, i.e., is my container image secure to deploy? This is how you make sure your container images are vulnerability-free, and that the images you built aren't modified before they're deployed. 
  3. Runtime security, i.e., is my container secure to run? This is how you identify a container acting maliciously in production, and take action to protect your workload.
Let’s dive a bit more into each of these.

Infrastructure security

Container infrastructure security is about ensuring that your developers have the tools they need to securely build containerized services. This covers a wide variety of areas, including:
  • Identity, authorization and authentication: How do my users assert their identities in my containers and prove they are who they say they are, and how do I manage these permissions?
    • In Kubernetes, Role-Based Access Control (RBAC) allows the use of fine-grained permissions to control access to resources such as the kubelet. (RBAC is enabled by default since Kubernetes 1.8.)
    • In Kubernetes Engine, you can use IAM permissions to control access to Kubernetes resources at the project level. You can still use RBAC to restrict access to Kubernetes resources within a specific cluster.
  • Logging: How are changes to my containers logged, and can they be audited?
    • In Kubernetes, Audit Logging automatically captures API audit logs. You can configure audit logging based on whether the event is metadata, a request or a request response.
    • Kubernetes Engine integrates with Cloud Audit Logging, and you can view audit logs in Stackdriver Logging or in the GCP Activity console. The most commonly audited operations are logged by default, and you can view and filter these.
  • Secrets: How does Kubernetes store secrets, and how do containerized applications access them?
  • Networking: How should I segment containers in a network, and what traffic flows should I allow?
    • In Kubernetes, you can use network policies to specify how to segment the pod network. When created, network policies define with which pods and endpoints a particular pod can communicate.
    • In Kubernetes Engine, you can create a network policy, currently in beta, and manage these for your entire cluster. You can also create Private Clusters, in beta, to use only private IPs for your master and nodes.
These are just some of the tools that Kubernetes uses to secure your cluster the way you want, making it easier to maintain the security of your cluster.

Software supply chain 

Managing the software supply chain, including container image layers that you didn't create, is about ensuring that you know exactly what’s being deployed in your environment, and that it belongs there. In particular, that means giving your developers access to images and packagers that are known to be free of vulnerabilities, to avoid introducing known vulnerabilities into your environment.

A container runs on a server's OS kernel but in a sandboxed environment. A container's image typically includes its own operating system tools and libraries. So when you think about software security, there are in fact many layers of images and packages to secure:
  • The host OS, which is running the container 
  • The container image, and any other dependencies you need to run the container. Note that these are not necessarily images you built yourself—container images included from public repositories like Docker Hub also fall into this category 
  • The application code itself, which runs inside the container. This is outside of the scope of container security, but you should follow best practices and scan your code for known vulnerabilities. Be sure to review your code for security vulnerabilities and consider more advanced techniques such as fuzzing to find vulnerabilities. The OWASP Top Ten web application security risks is a good resource for knowing what to avoid. 

Runtime security 

Lastly, runtime security is about ensuring that your security response team can detect and respond to security threats to containers running in your environment. There are a few desirable capabilities here:
  • Detection of abnormal behaviour from the baseline, leveraging syscalls, network calls and other available information 
  • Remediation of a potential threat, for example, via container isolation on a different network, pausing the container, or restarting it 
  • Forensics to identify the event, based on detailed logs and the containers’ image during the event 
  • Run-time policies and isolation, limiting what kinds of behaviour are allowed in your environment 
All of these capabilities are fairly nascent across the industry, and there are many different ways today to perform runtime security.

A container isn’t a strong security boundary 

There’s one myth worth clearing up: containers do not provide an impermeable security boundary, nor do they aim to. They provide some restrictions on access to shared resources on a host, but they don’t necessarily prevent a malicious attacker from circumventing these restrictions. Although both containers and VMs encapsulate an application, the container is a boundary for the application, but the VM is a boundary for the application and its resources, including resource allocation.

If you're running an untrusted workload on Kubernetes Engine and need a strong security boundary, you should fall back on the isolation provided by the Google Cloud Platform project. For workloads sharing the same level of trust, you may get by with multi-tenancy, where a container is run on the same node as other containers or another node in the same cluster.

Upcoming talks at KubeCon EU 

In addition to this blog post series, we’ll be giving several talks on container security at KubeCon Europe in Copenhagen. If you’ll be at the show, make sure to add these to your calendar:
Note that everything discussed above is really just focused at the container level; you still need a secure platform underlying this infrastructure, and you need application security to protect the applications you build in containers. To learn more about Google Cloud’s security, see the Google Infrastructure Security Design Overview whitepaper.

Stay tuned for next week’s installment about image security!

My Path to Google: Annie Jean-Baptiste, Global Product Inclusion Evangelist

Welcome to the 23rd installment of our blog series “My Path to Google.” These are real stories from Googlers, interns, and alumni highlighting how they got to Google, what their roles are like, and even some tips on how to prepare for interviews.

Today’s post is all about Annie Jean-Baptiste. Read on!

Can you tell us a bit about yourself?
I am a Boston native, and went to school at the University of Pennsylvania, studying International Relations and Political Science. I love New England sports teams, my dog (who comes to work most days), travel (I speak five languages and was a nanny before working at Google), music (I play the cello), and dance (I have danced many genres all my life and most recently danced half-time at college basketball games).

I'm passionate about healthy practices for underrepresented communities and use my platform as an American Heart Association Spokesperson and One Young World ambassador to ensure equal access to resources for communities of color. I think my degree was actually very helpful for my roles at Google—multidisciplinary, global in nature—it taught me to seek out, value, and elevate different perspectives.

What’s your role at Google?
I am the Global Product Inclusion Evangelist for Google. I help ensure we build products for everyone, with everyone. I most recently worked on several projects for Black History Month, including a Google Docs easter egg, where if you typed in #blackhistorymonth and clicked on the explorer box, you got awesome content about black history! What I like most about my role is that I can fuse my background (I started in our Global Business Organization as an Account Manager) with my passion (inclusive products and services).

Complete the following: "I [choose one: code/create/design/build] for..."

I build for communities that typically have not had their voices at the forefront, but are brilliant, innovative, and changing the world!

What inspires you to come in every day?

I am constantly inspired by Googlers and their commitment to dreaming big and creating a world where everyone—no matter their background—can see themselves in our products and use technology to create a better world.

Can you tell us about your decision to enter the process?
My brother was actually a BOLD intern and encouraged me to apply. I was a senior in college and didn't think Google was for me, given my non-tech background, but I deeply believed in making information universally accessible and useful. I was worried about not fitting in or getting the job, so I was so excited to get it AND be able to move back to the Cambridge office to be close to my family. I stayed in that office for four years, and it's still my favorite office to date!

How did the recruitment process go for you?

I applied directly and Google came to my university. I remember how friendly my recruiter was (fun fact: he had been a recruiter previously at my high school), and I also very much appreciated starting with a cohort of new grads—it made the process super fun.

What do you wish you’d known when you started the process?
That there are so many roles at Google—you don't have to be an engineer or a certain type of person to work here. In fact, my team's mission is to make sure that there are diverse perspectives, so we can build products for everyone.

Can you tell us about the resources you used to prepare for your interview or role?

For the interview, do your research—keep up with current events, what's going on in the tech industry, etc. Have a position on what excites and intrigues or challenges you in the tech landscape. Think of questions for your interviewer as well—it needs to be a fit for you, too!

Do you have any tips you’d like to share with aspiring Googlers?
Have a deep commitment to always learning. Ask questions. Be humble. Think about those voices you typically don't hear and how to ensure they have a seat at the table.

API design: Which version of versioning is right for you?

There's a lot of advice on the web about API versioning, much of it contradictory and inconclusive: One expert says to put version identifiers in HTTP headers, another expert insists on version identifiers in URL paths, and a third says that versioning of APIs is not necessary at all. (For some examples of those divergent views, take a look at this blog post and its bibliography and this interview with the author of the original REST dissertation).

With all this information, who’s an API developer to believe?

Here on the Apigee team at Google Cloud, we design, use and see a lot of APIs, and have developed some strong opinions about the right way to version them. My aim is to bring some clarity and offer unequivocal practical advice.

A significant part of the confusion around API versioning stems from the fact that the word “versioning” is used to describe at least two fundamentally different techniques, each with different uses and consequences. Understanding the two different meanings of API versioning is a prerequisite to deciding how and when to use each.

Type 1 versioning: format versioning

Consider the example of a bank that maintains accounts for customers. These accounts have been around for a long time and customers can get information about these accounts through multiple channels (the postal service, the telephone or the bank website, for example).

In addition, the bank has a web API that allows access to accounts programmatically. At some point, the bank sees a way to improve the web API; to attract more developers to it they decide to introduce a new version. I don't think there's an API designer who hasn't one day wished they had organized the information in some request or response differently.

The important point in this example is that version 1 and version 2 of the API both allow access to the same bank accounts. The API change introduces no new entities; versions 1 and 2 simply provide two different "formats" [my word1] for manipulating the same bank accounts.

Further, any change made using the version 2 API changes the underlying account entity in ways that are visible to clients of the version 1 API. In other words, each new API version defines a new format for viewing a common set of entities. It’s in this sense that I use the phrase "format versioning" in the rest of this post.

Format versioning seems straightforward, but it presents a technical challenge: how do you ensure that any changes made to an entity using one version of the API are seen correctly through all other versions of the API, and how do you ensure that changes made by older clients don't undo or corrupt changes made by newer clients?

In practice, this means that format versioning often can’t accommodate major functional changes. Another problem is that if a lot of format versions are introduced, the server code can become bloated and complex, raising costs for the API publisher.

Type 2 versioning: entity versioning

Given that format versioning can be complex to implement, and that it cannot be used for substantial changes that would cause older API clients to stop working, it’s a good thing that there’s another way to version APIs.

Consider how car manufacturers do versioning. Car manufacturers typically introduce a new generation of popular models every 4 or 5 years. Car model generations are sometimes also called marks; they're a form of versioning. When you buy a specific car of a particular model, it’s a generation 2 car or a generation 3 car, but not both. Car manufacturers will recall cars to fix faults, but they can’t make your generation 2 car look and behave like a generation 3 car on demand.

This model can work well for software too. Extending the bank example, imagine that the bank wants to introduce checking accounts based on blockchain technology, which requires the underlying data for the account to be organized quite differently. If the API that was previously exposed for accounts made assumptions that are simply not compatible with the new technology, it's not going to be possible to read and manipulate the blockchain accounts using the old API. The bank’s solution is the same as the car company’s: introduce "version 2" checking accounts. Each account is either a conventional account or a blockchain account, but not both at the same time. Each version has its own API that are the same where possible but different where necessary.

While "entity versioning" is attractive for its flexibility and simplicity, it also is not free; you still have to maintain the old versions for as long as people use them.

You could think of entity versioning as a limited form of software product lines (SPLs), where the product line evolves along a single time dimension. There's quite a bit of material on the general topic of SPLs on the internet.

New entity version or new entity?

From a technical perspective, introducing a new "entity version" is very similar to introducing a brand new entity type. The argument by Roy Fielding, the creator of REST, that you don't need to version APIs at all seems to be based on this idea.

Fielding makes an important point, but there are good reasons not to present a new API for similar concepts as something completely unrelated. We have all seen advertisements that say something like "Acme Motors introduces the all-new model Y," where model Y is an existing car model that Acme Motors has been selling for years. Not every statement made in car advertisements is accurate, but when car companies say "all-new," they're usually being truthful in the sense that there isn't a single part on the new model that is the same as on the old one.

So if the model is really "all-new," why is it still a model Y, and not some completely different model? The answer is that the manufacturer is choosing to emphasize brand continuity; although it's "all-new," the new model serves the same market segment in a similar way, and the manufacturer wants to leverage its existing investment in the model Y brand.

The bank has a similar choice to make when it introduces accounts based on blockchain technology. Although the new accounts are based on a different technology, they provide all of the basic capabilities of traditional accounts to the same customers. They may offer additional capabilities, or they may just hold the promise of greater security, or shorter delays in transferring money. The bank likely chooses to present them as a new version of their traditional bank accounts, rather than a completely different financial product.

One of the reasons why this form of versioning works well for car companies is that customers replace their cars every few years, so there's a natural migration from older to newer inventory over time. Banking customers may keep bank accounts for a long time, so the bank may want to offer to automatically migrate their customers to move them onto the new version more quickly. If your company's products are digital technology products, the natural inventory turnover may be even more rapid, which makes this versioning model even more attractive.

When is versioning required?

It turns out that in practice, many APIs don’t need versioning of either kind. We can say with certainty that some of our own APIs (Apigee’s management API is one example) have never had the need for a subsequent version or only in limited portions of the API.

One reason why many APIs never need versioning is that you can make many small enhancements to APIs in a backwards-compatible way, usually by adding new properties or new entities that older clients can safely ignore. Your first thought should always be to try to find a backwards-compatible way of introducing an API change without versioning; versioning of either sort should only be attempted if that fails. Fortunately, there are things you can do up front when designing your API to maximize the number of changes that can be made in a backwards-compatible way. One example is using PATCH instead of PUT for updates. You can also add a couple of random and meaningless properties to every entity representation; this will test the clients' ability to ignore future properties they haven't seen before.

One of the simplest changes that might motivate a version change is to change the name of a particular property or entity type. We all know that naming is hard, and finding the right names for concepts is difficult even when the concepts are clear. Names that were carefully chosen during development often become obsolete as concepts evolve and ideas become clearer. A format version can be an opportunity to clean up nomenclature without changing the fundamental meaning of entities and their properties. Format versioning lends itself to this sort of change—the same changes can be made by old and new clients using different names for the same things.

Another example that can motivate a version change is restructuring the representation of a resource. Here's an example of two ways of structuring the same information in JSON:

{"kind": "Book",
 "name": "The Adventures of Tom Sawyer",
 "characters": {
   "Tom Sawyer": {"address": "St Petersburg, Mo"},
   "Huckleberry Finn": {"father": "Pap Finn"}

{"kind": "Book",
 "name": "The Adventures of Tom Sawyer",
 "characters": [
   {"name": "Tom Sawyer", "address": "St Petersburg, Mo"},
   {"name": "Huckleberry Finn", "father": "Pap Finn"}

One of these formats encodes the list of characters as a JSON object keyed by the characters' name, and the other encodes it as a JSON array. Neither are right or wrong. The first format is convenient for clients that always access the characters by name, but it requires clients to learn that the name of the character is to be found in the place that a property name is usually found in JSON, rather than as a property value. The second format does not favor one access pattern over another and is more self-describing; if in doubt, I recommend you use this one. This particular representation choice may not seem very important, but as an API designer you're faced with a large number of options, and you may sometimes wish you had chosen differently.

Sadly, there's no practical way to write API clients that are insensitive to name changes and changes in data representation like these. A version format allows you to make changes like this without breaking existing API clients.

Browsers are able to survive HTML webpage changes without versioning, but the techniques that make this work for browsers—e.g., the ability to download and execute client code that is specific to the current format of a particular resource, enormous investment in the technology of the browser itself, industry-level standardization of HTML, and the human user's ability to adapt to changes in the final outcome—are not available or practical for most API clients. An exception is when the API client runs in a web browser and is loaded on demand each time an API resource is accessed. Even then, you have to be willing to manage a tight coordination between the team producing the browser code and the team producing the API—this doesn't happen often, even for browser UI development within a single company.

A very common situation that usually requires an entity version change, rather than just a format version change, is when you split or merge entity hierarchies. In the bank example, imagine that Accounts belong to Customers, and each Account entity has a reference to the Customer it belongs to. Because some customers have many Accounts, the bank wants Accounts to be grouped into Portfolios. Now Accounts need to reference the Portfolio they belong to, not the Customer, and it's the Portfolio that references the Customer. Changes like this are hard to accommodate with format versions, because older clients will try to set a property linking an Account to a Customer and newer clients will try to set a property linking an Account to a Portfolio. You can sometimes find ways to make both sets of clients work in cases like this, but more often you are forced to introduce new entity versions, each of which is updated using only one API format.

The sort of structural changes that force a new entity version usually introduce new concepts and new capabilities that are visible to the user, whereas the changes handled by format version changes are more superficial.

In general, the more clients an API has, and the greater the independence of the clients from the API provider, the more careful the API provider has to be about API compatibility and versioning.

Providers of APIs sometimes make different choices if the consumers of the API are internal to the same company, or limited to a small number of partners. In that case they may be tempted to try to avoid versioning by coordinating with consumers of the API to introduce a breaking change. In our experience this approach has limited success; it typically causes disruption and a large coordination effort on both sides. Google uses this approach internally, but at considerable cost—this article describes some of Google's investments to make it work. It is usually much better for API providers to treat internal users and partners as if they were external consumers whose development process is independent.

Choosing the appropriate technique

You can probably see already that format version and entity versioning are fundamentally different techniques that solve different problems with different consequences, even though they both sail under the flag of versioning.

So when should you choose to do format versioning versus entity versioning? Usually the business requirements make the choice obvious.

In the case of the bank, it isn’t feasible to introduce a new entity version of an account in order to enable an API improvement. Accounts are stable and long-lived, and moving from old accounts to new ones is disruptive. A bank is unwilling to inconvenience its banking customers just to make life better for API developers. If the goal is just to improve the API, the bank should pick format versioning, which will limit the sort of changes that they make to superficial improvements.

The bank should consider introducing a new entity version if there's significant new value that it wants to expose to its banking customers, or if it's forced to do so for security or regulatory reasons. In the case of blockchain accounts, there may be publicity value as well as practical value. Entity version upgrades are less common than format versioning changes for established services, but they do happen; you may have received messages from your bank telling you about a significant technology upgrade to your accounts and alerting you to actions you need to take, or changes you will see.

Entity versioning puts an additional burden on API clients, because the older clients cannot work with the newer entities, even though they continue to work unchanged with the older ones. This puts pressure on client developers to produce a new client application or upgrade an existing one to work with the new API.

Entity versioning can work well for technology products, where the the users of the API and the core customers are often one and the same and rapid obsolescence is considered normal.

How do you implement the different versions of versioning?

On the web, you often see conflicting advice on whether or not a version number should appear in the URLs of a web API. The primary alternative is to put the version ID in an HTTP header. The better choice depends on whether you're doing format versioning or entity versioning.

For format versioning, put the version identifier in an HTTP header, not in the URL. Continuing the banking example, it’s conceptually simpler for each account to have a single URL, regardless of which format the API client wants to see it in. If you put a format version identifier in the URL, you are effectively making each format of each entity a separate web resource, with some behind-the-scenes magic that causes changes in one to be reflected in the other.

Not only is this a more complex conceptual model for users, it also creates problems with links. Suppose that in addition to having an API for accounts, the bank also has an API for customer records, and that each account contains a link to the record for the customer that owns it. If the developer asks for the version 2 format of the account, what version should be used in the link to the customer record? Should the server assume that the developer will also want to use the version 2 format of the customer record and provide that link? What if customer records don't even have a version 2 format?

Some APIs that put version identifiers in URLs (OpenStack, for example, and at least one bank we know) solve the link problem by having a “canonical” URL for each entity that's used in links, and a set of version-specific URLs for the same entity that are used to access the entity's format versions. Clients that want to follow a link have to convert a canonical URL in a link into a version-specific URL by following a documented formula. This is more complex for both the provider and the client; it's simpler to use a header.

The usual objection to putting format version identifiers in a header is that it's no longer possible to simply type a URL into a browser to test the result of a GET on a specific version. While this is true, it's not very hard to add headers in the browser using plugins like Postman, and you'll probably have to set headers anyway for the Authorization and Accept headers. If you'ew using the cURL shell command to test your API, adding headers is even simpler. You'll also need more than just the browser to create, update or delete requests to your API, so optimizing for GET only helps for one scenario. Your judgement may be different, but I have never found it very onerous to set a header.

There's no standard request header that's ideal for the client to say what format version it wants. The standard "Accept" header specifies which media types the client can accept (e.g., json, yaml, xml, html, plain text), and the standard "Accept-Language" header denotes which natural languages the client can accept (e.g., French, English, Spanish). Some API designers (e.g., the authors of the Restify framework) use a non-standard header called "Accept-Version". If you're doing format versioning, I recommend this header. The standard "Accept" headers allow the client to give a list of values they accept, and even provide a weighting for each. This level of complexity isn’t necessary for "Accept-Version"; a single value is enough. If you're meticulous, you should set a corresponding "Content-Version" header in the response. Further, it can be useful for clients if the server also puts the format version in the body of the response; in fact, if the representation of one resource is embedded in another, the body is the only place to put it. [This argument applies to a number of the standard headers too: e.g., Etag, Location, and Content-Location.]

By contrast, if you're doing entity versioning, the version identifier will appear somewhere in the URL of each entity—usually either in the domain name or the path. Users of the API do not have to be aware of this; for them, it's just the entity's URL. The version identifier will appear in the URL because the URL has to contain information for two different purposes: for routing requests to the correct part of the implementation for processing, and for identifying the entity within that implementation. Because requests for entities that belong to two different entity versions are almost always processed by a different part of the implementation or use different storage, the version identifier (or a proxy for it) must be somewhere in the URL for your routing infrastructure or implementation to use.

Coincidentally, banking provides a simple illustration of the principle that identifiers contain information for both routing and identification. If you have a checking account at a U.S. bank (the details are different in other countries, but the idea is similar), you'll find two numbers at the bottom of each check. The first is called the routing number. It identifies the institution that issued and can process this check. The second number identifies the check itself. Conceptually, entity URLs are like the numbers at the bottom of a check, though their formats may be different.

Do I have to define my versioning strategy up front?

You'll sometimes hear the advice that you must define a versioning strategy before you release your first version, or evolving your API will be impossible. This is not true.

You can always add a new versioning header later if you find the need to do format versioning and you can always add new URLs for new entities for a different entity version. Any requests that lack the format versioning header should be interpreted as meaning the first format version. Since instances of a new entity version get new URLs, you can easily introduce a version ID in those URLs without affecting the URLs of the entities of the first version. The new URLs may use a new hostname rather than adding path segments to URLs on the original hostname; whether or not you like that option will depend on your overall approach for managing hostnames.

Procrastination can be good

Laziness is not the only reason why you might not add versioning to the initial version of your API. If it turns out that versioning is never needed for your API, or for significant portions of your API, then the API will look better and be easier to use if it doesn’t include versioning in its initial release.

If you introduce an "Accept-Version" header in V1 of your API in anticipation of future "format versions" that never materialize, then you force your clients to set a header unnecessarily on every request.

Likewise, if you start all your URLs with the path prefix '/v1' in anticipation of future "entity version" introductions that never happen, then you make your URLs longer and uglier than they need to be.

More importantly, in both cases you introduce a complex topic to clients that you didn’t need to introduce.

Some more versioning tips

If you use versioning, make it clear what sort of versioning you use. If there'a a field in your HTTP requests and responses that says "version: V1," what does that mean? Does V1 apply to the persistent entity itself (entity versioning), or does it reflect the format in which the client asked to see the entity (format versioning)? Having a clear understanding of which versioning scheme or schemes you use helps your users understand how to use your API as it evolves.

If you're using format versioning and entity versioning together, signal them with different mechanisms. Format versions should go in headers—Accept-Version and Content-Version—in the request and response. Format versions can also be included in the bodies of responses and requests, for those requests that have them. Entity versions (which are really part of the entity type) belong in the request and response bodies; they're part of the representation of the entity.

Do not try to put versioning identifiers of either kind or entity type identifiers into the standard Accept or Content-Type headers; those headers should only include standard media types like text/html or application/json. Avoid using values like application/v2+json or application/customer+json; the media-type is not the place to try to encode version or type information. Unfortunately, even some of the web standards do this the wrong way, for example application/json-patch+json.

Don't put words like "beta" or "alpha" in version IDs for either format versioning or entity versioning. When you move from alpha to beta, or beta to general availability, you're making a statement about your level of support for the API, or its likely stability. You don't want to be in a position where the API version changes just because your level of support changes; you only want to change the version if there's a technical or functional reason for changing it. To illustrate this point, imagine I am a customer who develops a number of client applications that are using the V1beta4 version of an interface—a late-beta version. The API provider declares the product to be GA, and introduces the V1 version of the API, which is actually exactly the same as the V1beta4 API, since there were no breaking API changes between V1beta4 and GA. The V1Beta4 version of the API is still available, so my client applications don't break, but the language of the support agreement is clear—only users of the V1 version get full product support. The change to my client applications to upgrade to V1 is small—I only have to change the version number I'm using, which may even be as simple as recompiling with the latest release of the vendor-provided client libraries—but any change to my applications, no matter how small, needs to go through a full release process with QA testing, which costs me thousands of dollars. This is very annoying.

Hopefully this post helps bring a little more clarity to the topic of API versioning, and helps you with your design and implementation choices. Let us know what you think.

For more on API design, read the eBook, “Web API Design: The Missing Link” or check out more API design posts on the Apigee blog.

1 Representation would be another word for this concept that might be better aligned with REST terminology. For reasons I can't explain, the term "representation versioning" is not as appealing to me as "format versioning".