API First at Adobe: Best Practices for Creating Good APIs and Getting Extensibility Right
Adobe is moving towards becoming an API-first platform, which means that everything is built upon a robust set of APIs. This set is the first and most important way to access and interact with Adobe products (check out the three principles of API-first design), and data can flow freely between Adobe tools and third-party software.
To find out what really makes a good API and dive deeper into the benefits of Adobe’s API-first approach, we talked to Klaasjan Tukker, director of product management for Adobe Experience Platform. Klaasjan, who has been at Adobe for over 10 years in various customer and partner facing roles, is now responsible for third-party integrations and extensibility and working with strategic partners to understand their requirements and driving the API-first strategy for Adobe Experience Platform.
What are the main characteristics of a good API?
In an API-first domain, the API is the main point of interaction with developers. I treat it the same as human interaction: you need to have good vocabulary, grammar, and the intent and understanding of a sentence in order to, even without hearing the intonation in a voice, understand what it is about.
With an API, my benchmark is the same. How is the language crafted? There are languages in Europe, which you would qualify as beautiful because of the way they use words or express things. People like the sound of French, the specificity of Italian, and the crispness and compactness of the English language. If you look at the characteristics of an API, you can very quickly see if a developer has put effort into naming the end points and operations and whether it’s consistent. In today’s world of microarchitectures you’re not building one service, you’re dealing with multiple services that do multiple operations, and it’s almost like a conversation with multiple people. You want to avoid needing to speak different dialects within the same language, or even worse, different languages.
So I think a good API is not only readable — that is table stakes — but pleasant to work with and almost reads like a book. Once you write code against it, the person observing the code understands what the other party does.
How does Adobe create APIs?
Adobe is a very large organization with a lot of individual groups. There are developers with different maturity levels when it comes to developing API-first and architects that have been in this space forever. We’re good at defining standards. People need to adhere to internal defined web service standards and common principles. When you take a service or application that has been built by multiple teams, you won’t see the individual teams’ flavor in it. So the standardization of verbs and nouns that are being used is very important in how we create the underlying service that people are consuming, which is then governed by an architecture board or an API review board inside of Adobe.
What are the benefits of Adobe’s API-first approach?
The benefits of the approach have to do a lot with modern computing. If you go back to when you would buy a floppy disk with software on it, you would put it into your system, run it and then get the user interface. We have evolved and gone into cloud computing. Customers are not only expecting ready-made software that they can log into and work with. They’re expecting software that they, if needed, can integrate with on the run. The patterns are very different.
The API-first approach means that first of all you use web technology before you enter, so you have a browser-based user interface, and the communication between the browser and the back-end service is in REST. The developer starts to think about the operations being the first contact element. That means you can build a whole system without a human user interface but still do all the operations. The benefit is that if someone doesn’t like the provided user interface or needs to orchestrate the workflow differently, they can call in the very same APIs. The APIs that Adobe is using to build our processes and user interfaces are the same APIs that a third-party developer can use to interact with.
It’s difficult at first because it’s a mindset change, but you will meet a lot of requirements for integration that customers have when they start using software or when they start evaluating enterprise software. API-first is a little checkbox, and then you move on to the next thing to evaluate.
What kind of best practices should developers keep in mind to get extensibility right?
I’m trained as a software engineer but I work in product management nowadays, and API-first starts with a product manager. We like to write use case stories for end users, but we’re also responsible for the product, and that means the service and not just the UI on top of it. As you spec out and define a system, your first point of assessment is interacting with the API through, for example, Postman before going into the user interface. A lot of product managers might skip that step but it’s important to remember that the service is your product as well.
Developers, on the other hand, like to do things quickly. You get a task and just build it. The first version always functions but it’s not really there. You might have used odd variable names and sub-optimal algorithms and will have to refactor again and again. When you’re in a high pressure environment, you might not always get to that point, so make sure that what you write meets certain required standards, and remember that what you write is going to be consumed by someone else. It’s very safe to write code that only you will be using, and when you leave it’s someone else’s problem to maintain, but you need to understand that your code, the moment you compile or deploy it, is going to be used and consumed by other people. When you understand that it’s not only being consumed by a colleague, who sits next door or in the next building, but by a customer, all of a sudden the mindset changes and you realize it needs to be better quality. So please build with third-party consumption in mind because otherwise you will see people cutting corners and needing to go through two or three steps to really get to API-first, good quality software.
What are the biggest mistakes developers make when creating APIs?
Developers want to get the job done, which is great, but sometimes they need to stop, think, and act. How much time do people spend on finding a name for their children? And how much time does a developer on average think about naming a variable, service or an endpoint in the path?
An API could live for five to ten years or even longer. The integration world would look way better if developers spent a little bit more time on naming things, the same way they name their kids.
The notion of ‘stop, think, act’ is very important because once you’ve created something, there is hardly a way back. Okay, you can refactor software internally but the external signature is there to stay. The moment I hand over the signature to a API consumer, I’m locked in and can’t change the API easily anymore. In the API-first approach, you first define the API specification, the signature, and that’s something you want to put through a clear review before implementing it using tools like Swagger.
Unfortunately, developers often build the whole thing first and then write the specification afterwards. Most of the time they cut corners in naming, and that goes back to my very first point around language. We’re building a language, a conversation.
What are the advantages of Adobe Experience Platform for developers?
Adobe operates in a very specific business area. We deliver software for great digital experiences. To do that, we need to understand our consumer, as such consumer data, their behavior, and the attributes that they represent are very important, and so are the content that you need to work with and the quality of that content. Adobe Experience Platform is a platform as a service that allows developers to build digital experience workflows by combining APIs that operate in the content space as well as data space. We combine that with a very rich stack of big data services to bring data together, harmonize it, and then to understand the individual attributes of a consumer.
Adobe Experience Platform provides that higher level capability out of the box without the need to do the low-level plumbing, which is a major advantage for a developer working with content and data. If you look at the world of software engineering, you would write low-level to CPU, then you would have an operating system and a programming language, and it would become more and more abstract.
Now you have the cloud as your operating system and Adobe Experience Platform is really a layer on top of that focusing on solving things quickly for digital experience businesses.