Profiling Adobe APIs
23 Jan 2020
As I was profiling APIs on my list of APIs I found myself profiling Adobe. I am moving through the list of companies alphabetically, so you can see how far along I am. Anyways, like any other large company I need to make a decision about how I am going to manage the profiling of different API products and lines of business. Companies like Amazon, Google, Azure, and Adobe have large numbers of APIs and I always know I will need to have some sort of plan for documenting everything that is going on. With Adobe, I am going to track everything in a single GitHub repository, but will be working to create separate API definitions (OpenAPI and Postman collections) for each of the individual APIs being offered.
To provide some context, it helps to understand why I profile APIs in the first place. As the API Evangelist I review public API operations studying how API providers are doing what they do. I then aggregate the "building blocks" of their public operations into a master set of reserarch that I use to drive my storytelling and API strategy workshops. So, with the Adobe APIs I'm not looking to review their API operations as much as I am looking to understand how they operate, and develop an understanding of how far along they are in their enterprise API journey. As with any profiling of a company, I begin by Googling their name pus API, but then dive as deep as I can into the details of what I find with each click.
When you Google Adobe APIs you get this main landing page with the tagline, “APIs and SDKs for all Adobe products – create mobile, web and desktop apps”. You can tell Adobe is working hard to bring together their APIs under one big tent, with the following main areas to support developers:
- Landing Page - Adobe API landing page.
- Authentication - Overview of authentication.
- Open Source - An open source page.
- Blog - Their tech blog for their APIs.
- GitHub - A dedicated GitHub account.
- Twitter - A dedicated Twitter account.
- YouTube - A dedicated YouTube account.
- Support - The support for API developers.
- Release Notes - Release notes for APIs.
- Cookies - The cookies policy.
These building blocks provides the basis for their API operations, providing a single landing page for brining everything together, and help folks find what they are looking for when it comes to APIs for all of the Adobe products. When listing out their products Adobe breaks them into three distinct categories:
- Creative Cloud
- Document Cloud
- Experience Cloud
- Adobe Experience Platform
I worked my way through each of the Adobe products, there is a mix of available resources for each of their lines of business, but I am purely looking specific HTP API signals that I can profile and add to my index of APIs. While looking through each of these area I’m looking for the elements that help me quantify the value being offered by each of the Adobe APIs. While looking through the Adobe I/O program I can ame across 15 APIs, that had enough meat on the bones for me to profile and add to my index.
First I came across Adobe Launch, a “platform to develop and deploy tag management extensions into the Adobe ecosystem.” While profiling I documented the following building blocks supporting operations.
- Landing Page - Domain dedicated for Adobe Launch.
- Join Slack Group - You can request to join their Slack group.
- User Documentation - Overall documentation for Adobe Launch.
- API Documentation - The API documentation for Adobe Launch.
- Blog - They have a tag dedicated to the API as part of the tech blog.
- Example Projects - They provide some example projects.
- Tooling - They have some tooling available.
It was notable that Adobe publishes documentation using GitHub , allowing anyone to edit the documentation. Another thing I found worth highlighting was that they use the JSON API specification as part of their API first approach to delivering the platform.
I have to be honest I don’t fully understand what the ADobe Launch API does. I am not intimate with how the Adobe experience platform works, but I wanted to try and understand the value it delivers within a couple minutes of reading through the API documentation, and other supporting building blocks. Overall, it could use a little more work to help on-board new users, but maybe it is a pretty Adobe ecosystem focused thing, and I am not in the know.
One of the things I like about doing these types of profiles is the little nuggets I find about how teams are doing what they do. Here are two of the interesting nuggets I found while profiling the Adobe Launch API:
- Serverless Newman - A serverless project that executes postman tests via newman in AWS lambda and writes test results to cloudwatch logs using winston. The Lamdba will return with an error if the test fails / does not complete.
- Reactor Postman - A Postman collection of Reactor API examples for Adobe Experience Platform Launch. This collection shows a simplified use case of provisioning a new property, creating extensions rules and data elements, and initiating a library build.
These open source projects gives me material for additional stories about how Adobe delivers their API infrastructure, but also how they use Postman as part of their API life cycle. I’d like to spend more time playing with the Adobe Reactor Postman collection, and learn more about how it all works in concert with their platform.
Next, I profiled the Adobe Sign API, providing “a powerful and easy way to integrate Adobe Sign functionality into your own applications.” Here are the building blocks I found while profiling the Adobe Sign API, and helping support developers.
- User Documentation
- Interactive Documentation
- Postman Documentation
- Sign Up
- Change Log
- SOAP Migration
- GitHub Organization
- Cloud Elements
You can see them exploring with different types of API documentation here by providing interactive documentation using a Swagger 1.2 definition, as well as Postman documentation with a Run in Postman button. With additional evidence of Adobe working to evolve the API with the SOAP migration, and the different approaches to documenting, and making their APIs available to a public audience.
Next, I looked into the Adobe Privacy Service API, which “provides a common, centralized facilitation of access/delete requests and opt-out-of-sale requests for private data.” A pretty interesting concept for an API, where I found the following building blocks supporting its operations.
The GDPR implications of this API are very interesting. I am going to set this API aside and spend some more time playing with as I work to generate a Postman collection from the Swagger 2.0. At first glance it looks like one of those APIs that can be used as a blueprint for other implementations, or maybe become an open source API that anyone can use.
Next, I looked at Cloud Manager, which is part of the Adobe Managed Cloud Services, and enables “organizations to self-manage Experience Manager environments in the cloud”. The Cloud Manager API enables Cloud Manager customers to interact with the same underlying capabilities exposed through the web UI in a fully programmatic fashion, allowing for integration of the Cloud Manager Continuous Integration / Continuous Delivery pipeline into other systems. There were just a handful of building blocks available for cloud manager.
With Cloud Manager I am seeing a common thread in how Swagger is used to deliver documentation, providing a Swagger 2.0 spec behind the scenes--something I will use to generate a Postman collection to help me further index the API as part of my research. I also notice that the Cloud Manager API documentation is hosted via GitHub along with other projects within a single AdobeDocs GitHub organization.
Now for the Target Manager API which “implements Target on client-side applications, server-side applications, mobile apps, IoT and export your Target data to third-party solutions.” Here are the building blocks for the Target Manager API.
- Landing Page
- User Documentation
- API Documentation
- Admin API Postman Collection
- Recommendations API Postman Collection
There isn’t a lot of meat on the Target Manager API bones, but they do prominently link to Postman collections for each of the APIs. Allowing you to, “ tailor and personalize your customers' experience so you can maximize revenue on your web and mobile sites, apps, social media, and other digital channels.”
Now for Adobe Primetime which, “brings TV to every IP-connected screen. It gives programmers and operators modular capabilities to stream, protect, analyze, and monetize video across desktops and devices, powering these experiences are a number of streaming technologies used to deliver content and advertising to Primetime video players.” These are the building blocks I identified for Adobe Primetime while looking around.
You can tell that Primetime isn’t quite fully baked as a web API, and posses many of the characteristics of a legacy API, relying on PDF only documentation, and other building blocks that will cause friction with developers, and slow down on-boarding.
Moving on to the Campaign Standard APIs which lets “you create integrations for Adobe Campaign Standard and build your own ecosystem by interfacing Adobe Campaign Standard with the panel of technologies that you use. There is just documentation for the API present in the help section.
The Campaign Standard API is a pretty classic example of an API that doesn’t get much attention, or supporting building blocks. Revealing the Adobe still has some significant investment ahead when it comes to standardizing how resources are distributed across different teams, and take more advantage of shared resources across APIs.
With the Analytics API you see a little more investment in providing “a collection of APIs that power Adobe Analytics products like Analysis Workspace, allowing for the creation of data rich user interfaces that you can use to manipulate and integrate data, create reports to explore, get insights, or answer important questions about your data.” Here are the building blocks I documented as I was learning about the Adobe Analytics API.
- User Documentation
- API Documentation
- Swagger 2.0
- Discovery API
- Reporting API
- OAuth in Postman
- Github Docs
There is a lot more meat on the Adobe Analytics API bones. There is a Swagger 2.0 behind things, and they leverage Postman to help with OAuth. Definitely more work to be done here, but the Analytics API clearly gets more resources and attention by the team and the community.
Next up is the User Management API which “provides programmatic access to the user accounts that are associated with your Adobe organization, integrating the API into your organization’s administrative applications and processes. You can use the API in scripts or programs to allow authorized administrators to create, update, and delete user accounts for your enterprise, and retrieve information about your Adobe users and their access to Adobe products." I only found documentation for the User Management API:
There was no OpenAPI, Swagger, or Postman collection for the API, but I will add o the list of API definitions I can create, or help encourage Adobe and the community to step up and contribute to. I’m guessing the Adobe User Management API can reduce friction for a lot of teams when it comes to orchestrating the use of Adobe products across the enterprise. The Adobe User Management API is definitely one of the more anemic Adobe APIs, and could use some more investment when it comes to its supporting elements, and would significantly benefit from shared resources made available across all of the Adobe APIs.
Next, Adobe I/O Events “offer you a powerful way to integrate your application with Adobe services and solutions. Starting with Creative Cloud Assets, Adobe Experience Manager, and Adobe Analytics Triggers, we are adding events across our entire range of technologies.” They don’t provide much beyond some robust user documentation.
Adobe I/O Events clearly provides a lot of value, but lacks many of the characteristics of a modern API, and like others would benefit from more resources, and an investment in shared resources across Adobe API teams.
Next up is an Audience Manager API, that provides a “data management platform that helps you build unique audience profiles so you can identify your most valuable segments and use them across any digital channel". LIke other Adobe APIs, it only has some user documentation to support its integration into other applications and systems.
The documentation says they are migrating to use Swagger, revealing more of the work that is occurring behind the scenes. I recommend skipping over the Swagger migration and upgrade to OpenAPI 3.0, so that you can take advantage of the evolution of the specification and the tooling it supports.
Now for the Places API which, “lets you work programmatically with your organization's point of interest (POI). The POIs are organized into libraries so that you can easily create grouped actions on these POIs. The APIs allow you to create, update, and delete your libraries and the POIs in those libraries.” The API isn’t fully public, and you have to sign up to get access.
I don’t fully see how the places API fits into the bigger Adobe picture. Which is kind of a theme I’m finding across the APIs I have been profiling. They all seem to have an individual purpose, but I don’t see a strong argument for how the API supports the overall Adobe platform objective.
While I was Googling to see what else I missed, I came across the CC Storage API, which “lets you access and modify assets stored in the Creative Cloud, the world's most popular creative platform.” All I found was this API documentation:
CC Storage seems like an API that should be getting a significant amount of investment. I am guessing that seamless integration of storage when it comes to Adobe customers would be a pretty huge priority, and one they would be willing to pay a premium for.
Last up is the Adobe Stock API, which “provides programmatic access to Adobe Stock content. You can integrate this API into your organization's applications and processes. You can use the API in scripts or programs to search for and retrieve Adobe Stock assets such as photos, videos, and vector files, and to license assets for your users.” All I have found to support is the following documentation.
The documentation for all of Adobes APIs feel like old school documentation for desktop software. Like storage API, I can only imagine the Stock API is a pretty high value API, and would significantly benefit from more investment, and availability as a modern set of APIs. Allowing people to seamlessly integrate and automate with Adobe Stock images across their applications and websites.
Adobe I/O Summary
It is clear that Adobe is working on bringing together the API vision across all lines of business under a single tent. It is also clear how hard that is to do this across a large established enterprise organization. There isn’t a lot of consistency across the APIs minus the nice looking landing page they have for Adobe I/O. I am going to go through each of the APIs that have a Swagger, and upgrade them to use OpenAPI 3.0, and generate Postman collections for each of the APIs, but alongside I have the following recommendations for the Adobe team(s).
- Definitions - Make sure there is a machine readable definition (OpenAPI and Postman collection) for each API. I am working on doing this as part of my research, publishing to GitHub, so if you want to collaborate on it, I'm here to help. Then let's train everyone at Adobe on why API definitions are so important to API evolution and adoption.
- Documentation - Invest in a single API definition driven approach to delivering documentation, either OpenAPI + ReDoc, or go all in on Postman for documentation. Train your teams and make sure they understand the importance of documentation being driven by an API definition, and consistently published for consumers to use.
I'd say let's start there. I will be investing in this as part of my API Evangelist reserarch. I want there to be complete API definitions for all of the Adobe APIs. Defining what is possible, and allowing consumers to use themn in other services and tooling. I will be publishing these API definitions to GitHub for additional community feedback and contributions, where I will also publish API documentation using Postman. So, I am happy to collaborate on this. I think once there is a complete (enough) API definition plus consistent documentation for each of the existing APIs things will look significantly different, and we can start thinking about other ways to tighten things up.
I fully get the value of Adobe products. Honestly though, I don't see the value in the Adobe APIs. I don't really even grasp what some of them do, and I don't see an overarching vision for how they work together and benefit Adobe or Adobe customers. I know the value is there, it just isn't pulled out in the design and deliver of the APIs. Something that can be significantly enhanced with just a few iterations, and by making sure there are API definitions, and consistent docs present. I am going to take all of this research and publish it to my API Monitoring system, and then publish the API defintions and documentation I have to GitHub. Then I'll step back and consider other areas I can contribute to the Adobe API journey from the outside-in, and I am also hoping some of the Adobe API teams will have reached out to me and initiatied conversations around what they'd like to see.