Before digging deeper into API Design, we need to understand what “API” stands for. We build the capabilities to interact with customers, partners, adjacent industries and even your competition. To do this, we will create "electronic touchpoints". In technical terms these are called Application Programming Interfaces or APIs. An API is a software intermediary that allows two applications to talk to each other and expose functionality outside of the application, domain or even company. It is a component that exposes well-described dataand functionality. Data between providers and consumers of an API, can be exposed in different formats. This means that APIs are exposing functionality and data through a uniform and multi-format interface. When we are talking about APIs, REST is the de facto standard. This means that APIs are resource based, taking into account RESTful principles.
Where does API Design fit in?
At Archers, we created a six-pillar program to get you started with API Management. The image below shows that we consider API design as an essential part to set up an end-to-end API program. However, all pillars have a significant impact on the API design decisions you need to take as an organization.
The set-up of a successful API program must start with a business strategy. This provides the objectives your organization want to realize, and how APIs contribute to the realization of those objectives.
Strategic objectives could be for example:
- Driving innovation by exposing data and functionality through APIs
- Improved engagement with business partners
- Connect business processes
- Improve working relationships
API governance concentrates on the documentation and the processes required to deliver qualitative APIs. The level of governance required within your organization has a direct impact on design choices you will make for your APIs.
Platform is about the technology capability, the chosen platform that exposes and implements your APIs. However, keep in mind that the framework and platform you are choosing to expose and implement your APIs, may limit the design choices that you are able to make!
Create your own API design approach
When organizations are looking at API design, they often try to copy the design approach from big companies like Netflix or Microsoft as they have some great public APIs. However, these guidelines do not cover all the aspects of API design, and above all these companies are probably targeting another kind of developer community. That is why we believe that API design needs to be tailored to the needs of your organization. There is simply no one size fits all solution!
So, when you start looking at API design, listen to your own needs and take into account the unique context of your organization. Consider your API maturity level and the targeted developer community. Also keep in mind that the chosen platform and targeted consumers have a significant impact on your API design.
Important API Design aspects
By knowing the consumers of your APIs, you will be able to build APIs that your consumer and/or developer community is willing to use. Although this means that a messaging style like SOAP can be used to build your APIs, we focus on design aspects for REST APIs as they are the standard in today’s API programs.
A selection from aspects that need to be taken into account when designing qualitative APIs:
- Concept of resources: they are the heart of your API and offer you a first glimpse on the functionality and data the APIs are exposing to customers. Always make sure that you are using terminology that API consumers can understand.
- Versioning: your APIs will evolve over time, so you need to choose a versioning strategy at the very beginning of your API program. Several versioning schemes exists for REST APIs, but these are made for the technical part of your API. When choosing the appropriate strategy take into account relevant aspects such as the number of APIs you will have, the number of API versions that you want to keep running in parallel with the production environments and your migration strategy to move consumers to a new version of your API.
Finding the right API design for your organization is not a one size fits all story. Make sure to align your APIs with the needs of your organization. Know your customers: are they internal or external? Differentiate your internal and external approach concerning versioning, terminology and HTTPS verbs. And last but not least: know your organization. Assess your maturity, get insight in the API maturity of your organization and know your framework and platform.
How ArcelorMittal crafted a tailor-made API Design Approach
ArcelorMittal is the world’s leading steel and mining company and produces high quality steel in various countries. In their pursuit of innovation and efficiency, they aimed to further optimize their supply & quality chain process. To achieve this, ArcelorMittal Flat Europe examined and reviewed their entire IT-landscape, ranging from software assets to integration capabilities. One of the resulting key decisions was to implement an API Management platform.
This API platform is one of the major building blocks of the Hybrid Integration Platform. ArcelorMittal aims to mainly use their APIs for internal integration of new applications: integration either via messaging (pub/sub) or APIs, integration within and between business domains and the creation of partner APIs.
Challenges of ArcelorMittal’s API program
Together with Archers, ArcelorMittal defined an API strategy and gave thought to the solution architecture. A reference architecture was defined to increase flexibility of software assets, a scope was determined for the to be managed APIs and practices and guidance on patterns were set up.
A second challenge was about API design and development, aiming to standardize the way APIs were built to increase quality and maturity. An API methodology for design and development was defined in order to integrate these newly build APIs in the existing application development lifecycle & DevOps processes. As a platform, the IBM API Connect platform was chosen.
How ArcelorMittal crafted their API design approach
“We started with our feet in the mud”, according to Ken Wauters, IT Manager at ArcelorMittal. “There were no standards for our development teams, no guidelines and it was up to each development team to develop their ownAPIs.APIs were also developed in the same sprint as implementation. Our approach was thus rather database-oriented API development than real API design.”
Time for action! ArcelorMittal defined the new foundations to standardize the way they build APIs. Secondly, they installed the API methodology embedded into a fully automated process into the development lifecycle.
Defining the API design foundations
API design guidelines were defined and a common language across domains was set up. However, this asked for some major shifts. First, there was the shift to product orientation (API as product), secondly to contract first (allowing ArcelorMittal to split design and implementation into different sprints)and thirdly towards a resource-based era of API designaiming to improve the quality and maturity of APIs.
“You can start from a well-known recipe, but you must tailor it to your specific enterprise culture, maturity and context. Based on practices, experiences and lessons learnt, we built our API design guidelines together with the key stakeholders of our development community “, according to Ken.
ArcelorMittal’s considerations for an API design methodology
A good API methodology was required to embed the new approach in the application development lifecycle, guiding the developer community through this culture change.
- When using APIs, you have to integrate them and automate them in the development lifecycle. Introducing APIs in your organization requires a massive cultural shift, so guidance only is not enough. ArcelorMittal provided the community with templates, generation tooling, automated CICD pipelines… to ease the life of their developers.
- These APIs need to be embedded into the development lifecycle to help achieving compliance to standards and guidelines. In doing so, ArcelorMittal got support from the business to ensure API security.
- The main driver of these governance considerations was to deliver the program functionally. When a proper domain analysis was done, ArcelorMittal reflected on the purpose of the APIs, identified the API consumers and the architectural design, resulting in a formal gate, the “contract gate”. API contracts are kept into a central repository. When a user tries to merge the contract to the master branch, a pull request for a review is automatically triggered.
API program next steps
“After 2 years of running the program, we realized a lot”, Ken states. As ArcelorMittal has a contract review now and the number of APIs is steadily growing, it’s time for them to extend the governance to the API portfolio level. They are also planning to install a review on the API granularity.
Now that there is more focus on the non-functional requirements, they are planning a second run on data provisioning patterns, giving guidance, evangelizing and reviewing the architecture.
Business product owners will be trained to take the ownership of APIs, the value of runtime governance (analytics) will be explored and the scope of the API program and platform will be extended to other business domains.
There is no magic cookbook for API Design. Keep in mind your enterprise culture, context and maturity when tailoring your API design approach. Handle a step-by-step approach to implement your design. Never skip guidance and methodology, they are necessary to successfully drive the change in your organization.