adidas APIs
As a part of my Good API ventures, I’ve had the pleasure to spend the past six months working for the adidas as API Designer and Evangelist.
Some of you might be wondering why one of the biggest shoemakers in the world needs APIs. But at the verge of the digital transformation where every company is a software company, APIs play a critical role in enabling interoperability, improving efficiency, reducing costs and communicating with partners and customers.
From order management, product inventory, e-commerce, and internal processes to mobile apps and communication with partners, adidas IT’s APIs are flourishing. Throw in the decomposition into microservices, emerging AR and VR technologies in the fashion industry and the IoT opportunity in the supply chain (estimated at $1.9T), and we are looking at dozens and dozens of enterprise APIs.
After the six months, I am still learning about different teams working on new APIs. The most recent pleasant “surprise” is the HR team. Everybody now wants an API! Or at least to integrate with other APIs.
However, having so many APIs with so many teams bring new problems. For instance, how to learn about company APIs? How to find whether there is an API for given functionality? What is the best way to design, document, develop and test APIs? What about security and publishing APIs? How should we educate others about our APIs? We needed to answer many questions and do lots of API designs and training.
When I first approached adidas, I was amazed by the maturity of their (enterprise architecture) approach to the APIs. Oldrich Novak, the enterprise architect in charge of the API initiative, knew all the right books (Amundsen, Richardson, etc.) and was determined to do APIs the “right way.”
The mission was clear. We were to bring all newly created APIs to the same level (Richardson maturity model, level 2 at the minimum; Web API design maturity model, level 2 at the minimum) and to ensure the unified API consumer experience across the whole enterprise. We aimed for a single source of truth for all APIs–one place where you could go and learn about every API within the organization.
How We Have Done It
The foundation of great APIs across any enterprise is people, respect, understanding, guidelines, tools, and processes — in this order.
Meeting with co-workers, understanding their needs and problems, and building new friendships and trust were the best parts of my job. Without the incredible people working at adidas, achieving our goals would not have been possible. And I have to repeat myself: wherever I went, I was pleased with the professionalism and the maturity of the approach. To have open-minded, supportive people who understand the motives and goals of what you are trying to achieve is a blast.
I’ve spent days and days learning current workflows, exploring existing APIs, and understanding business objectives and the tools of the trade. Together, we did a lot of API-First, REST, HATEOAS, and API Design training to boost existing knowledge.
Finally, after many iterations, we have settled the adidas API Lifecycle and adidas API Guidelines.
adidas API Lifecycle
We have adopted and extended the agile API Lifecycle I developed at Apiary a couple of years ago.
Every team has to start with the API design to establish the contract. Pending approval, this agreement is binding upon all parties in the API Lifecycle.
We are using Oracle+Apiary design platform to help us facilitate the design, contract verification, and API consumption, but most importantly, Apiary is helping us to keep the API designs consistent across the board using the automatic style assertions checks — the Apiary Style Guide. Finally, Apiary also serves as the single source of truth for all the adidas APIs.
After the extensive testing of many of the API management offerings, we decided on the Tibco Mashery as the API gateway solution.
When it comes to API integration tests and contract verification, we are using the Dredd testing tool. We run tests both locally and in Jenkins/TeamCity environments with the reporting to Apiary. This way, architects can get a clear picture of the implementation status and conformance to the design standards for every API.
adidas API Guidelines
adidas API guidelines is a living document that captures the process and rules of API design at adidas. It serves as the manual for building new APIs and modifying existing ones. The adidas API Guidelines is API design-time governance that also includes documentation of the complete API lifecycle process.
These are not the guidelines you might have seen before. adidas API Guidelines doesn’t focus on what HTTP status codes or methods are allowed, or how to design “beautiful” URIs. Instead, the guidelines are about:
1. Core API Lifecycle principles
2. API protocols we use at adidas
3. Message formats we pass around
4. Application-level semantics
These guidelines also come with non-functional requirements and recommendations both from the API evolution and API execution perspective.
We’ve tried to keep the guidelines minimal. That is why they do not include any discussion about why we’ve decided to go for a particular format or construct. There is no elaboration on the decisions made. These discussions happened offline, outside of the document.
The guidelines and sample APIs are completely open source. You can read the adidas API guidelines at GitBook and see many examples on GitHub. However, currently, all of the Adidas APIs are either internal or partner APIs and such I am not able to share with you any production API. We are looking at APIs that could be opened to the public, so we can share some of the cool services we are building.
There is still a lot of work ahead of us, especially when it comes to the application semantics, but we are already very pleased with the state of the adidas API Guidelines and its adoption by teams.
If you are building HTTP or REST APIs, I sincerely invite you to read the adidas API Guidelines and share your thoughts with us here in the comments or a pull request on GitHub!
Adidas has successfully embraced the digital transformation, as you can also judge from its earnings announcement and very aggressive targets for 2017.
After the six months, I am convinced the Adidas Enterprise Architecture API initiative is providing the right infrastructure needed for achieving these goals.
