But isn't API ecosystem just the external stuff?
API ecosystem is a term most often associated with companies providing open interfaces externally for third-party integrations and add-value application layer (most often the ones with a platform business approach).
I claim that for most companies the more important API ecosystem is the internal one. Internal API programs and the API First approach is important in developing functional overall integration architecture and development practices in modern large enterprises with ambitions for agility (and who doesn't at this point?).
Isn't this just SOA all over again?
Service oriented architecture (SOA) and the often associated enterprise service bus (ESB) used to facilitate integration between the different services rose to prominence in the 2000s. My take is that the SOA philosophy was (and is) a good one but the tooling and the ESB approach that traditionally has been associated to it didn't measure up. ESB approach with SOAP protocol, web services etc. have a few built-in issues.
When you think of how ESB model SOA often works in practice is that you have one team provide a core service (often an out-of-the-box external product with some customization) which exposes typically 1-4 services with a variety of different protocols (sometimes HTTP/json, sometimes SOAP web service, sometimes custom binary formats, etc.) via an API which is designed heavily from the perspective of the product itself. After this the team drops the gloves and the responsibility is often left up to an internal but separated integrations team to figure out how to provide an internally consistent API to the other teams to consume.
Essentially this means that the team with the best knowledge about both the technical and functional aspects of the underlying service does nothing about the API from re-usability and standards compliance point of view. The responsibility to define the re-usable and clear API which is easy to use by others (which are very often the stated goals of API creation) is thus left to a team which has by default no knowledge of the system, its requirements, its use cases or anything else and will need to learn it (add some broken phone to the specification chain in many cases). When phrased this way I'm sure you can start to see what kind of issues occur.
The ESB will inevitably end up containing business logic (information for usable APIs will need to be aggregated from multiple services making different assumptions), refinement requires mapping to a different format with some enrichment data databases ending up living close to the ESB, etc. This needs to be maintained and upgraded in cadence with the underlying systems. The cherry on top is that ESB vendors rarely provide or even enable modern CI/CD pipeline capabilities, robust versioning and diff tooling and to add insult to injury, often opt for low code graphical editing interfaces (which are great for small contexts and creating stuff quickly but often break at larger scales and disregard maintenance and lifecycle concerns).
The integrations team & ESB model leads to some issues already when creating the APIs. So how about maintenance? Well since the ESB ends up containing plenty of business knowledge implemented by people who're not the best experts on the underlying system, the ESB naturally also ends up with its share of bugs. Combine this with restricted visibility that is often not a feature naturally provided by ESB vendors (and thus left up to how well the governance is handled by the implementing organization) and you'll end up with a situation where very often the finger is pointed and blame assigned by default to the integrations team when something goes awry in the end-to-end pipeline. This often muddies up the responsibilities, increases MTTR (mean time to repair) and polarizes the internal development departments.
Naturally internal API ecosystem is no panacea - strong governance and architecture vision is required in both models but API First approach does offer solutions to a multiple fundamental issues with the SOA / ESB model.
So how does API First and internal API ecosystem help?
API First and internal API ecosystem are an evolution of service oriented architecture thinking suitable for modern microservice architectures (which are essentially just ways to design and manage large distributed systems at high level).
Here is an overview of how API First approach tackles the previously identified issues and what kinds of new complexities it brings with it (nothing is perfect, it's just tradeoffs all the way down).
API First principle
API First principle changes the overall dynamic of API design responsibilities. It borrows from the modern devops and agile cross-functional product or feature teams thinking in that the team is responsible for providing a working product as a service (maintenance included). The definition of the product is extended to include a re-usable API which follows the company's internal standards and is usable for at least the primary use cases by internal customers (i.e. other internal teams) as is. There is no centralized integrations team which needs to perform magic to transform a messy API into a re-usable one - it is one of the core responsibilities of the product team itself.
This means that the team with the best knowledge of both the technical and functional aspects of the product is also the one to design the API which it provides. While this means more responsibility for the team, it also removes several undesirable phenomena from the overall architecture and organization such as by often making it a lot clearer immediately which system has broken down when there is an issue with the end-to-end functionality and the defect analysis is thus almost automatically directed to the correct party much faster.
An important part of API First is that the API is actually useful to design before the implementation driven by business requirements and owned by the business owner of the system itself. This provides increased business alignment from the get-go and reduces communication barriers that often exist between business and development teams in traditionally structured development organizations. This doesn't mean that the business analyst needs to be one hand-writing Swagger or RAML specs (in fact no one should be hand-writing those) but even conceptually thinking from the perspective of API first is highly beneficial.
A non-obvious benefit from creating the API specification first and implementation after that is that it is very hard to accidentally make breaking changes or couple the internal structure of the implementation to the public interface. If you generate the API spec from code this becomes extremely easy - and causes downstream pain i.e. customer teams consuming your service will have to change their implementation and this couples otherwise independent teams together causing unnecessary organizational development overhead. Overall this tends to motivate better up-front API design since you know you'll end up doing more work when you notice change requirements later in the process (which still happens since we're all imperfect - but the frequency should be lower).
One consequence of this model is that a strong governance framework is required to align all teams' APIs with regards to the shared cross-cutting concerns like authentication, authorization, specification style, common header fields etc. It's very easy for some drift to start happening after multiple teams get the freedom and responsibility to develop and expose their APIs so the architectural guardrails need to be well thought out, tested and evaluated before really starting to internally scale up this approach.
This is where the tooling of the internal API ecosystem steps in.
Internal API ecosystem tooling
To really work, the API First principle alone isn't enough - it requires good tooling, governance, training and practice. The details of the tooling are often highly dependent on the individual company context but there are some must-have components with important responsibilities and features.
Internal developer portal
This is the most visible and centralized part of the internal API ecosystem. All internal APIs (parhaps with the exception of experience layer team / application specific external APIs depending on how you structure your ecosystem) should be published here and should be visible to all developers. It's also a good idea to connect this API visibility to enterprise architecture and service landscape documentation / tooling to improve the overall visibility and observability of internal service offering.
Internal dev portal should provide many of the same capabilities as an external i.e. allow developers to self-onboard, manage their team's (or whatever is permissions structure you decide on) APIs (though ideally this happens only via automated CI/CD pipelines), subscribe to all development and testing environment APIs they want, have the ability to play with sandbox queries, facilitate API lifecycle management e.g. by providing communication support for new version publishing and deprecation of old ones, usage statistics and much more.
Dev portal should also be connected to the API gateways at least enough to be able to provide all end-point information in addition to the API specs, information on authentication and authorization etc.
API Gateways
This is where we get to the context which is very highly dependent (even at high level) on the corporate context. API gateways are important authentication & authorization & policy enforcement checkpoint to segregate different security contexts - both externally and internally. They're may also be useful as common endpoints to hide implementation details (in a large multicloud ecosystem there might be one or more API gateways which guard all services hosted in AWS and a separate set for GCP for example) and also potentially for intra-platform traffic as well (e.g. between different AWS accounts) which may simplify traffic routing configuration.
In case the different platforms are highly distributed geographically the gateway architecture is likely to be important for latency optimization as well while keeping service discovery as simple as possible (not considering intra-cluster discovery within e.g. Kube clusters or service mesh clusters with connected data / control planes which may obviate the requirement for API gw based routing).
Note that it's often desirable to have the API / service specific routing and policy configuration to be connected to internal dev portal publishing process and centralized. I won't delve more into this subject here though.
It's important that API gateways don't perform any mapping or other payload ETL operations to keep them lightweight and to avoid the issues of the centralized ESB integrations teams. It's essential that the teams' services expose sensible APIs at the origin.
Some additional roles and responsibilities that the gateways may have:
- Rate limiting (DDOS protection)
- Authorization checks
- Scope enforcement (e.g. it's possible to use the same gateway instances for both internal and external calls signed by trusted authentication providers but with different scopes which define which services they can call)
API Design and publishing tooling
You'll want to have a standard CI/CD pipeline for managing and publishing the API specifications (separate from service implementation) following everything-as-code principle. Ideally service and API provider teams should have no reason to directly interact with the internal developer portal or gateway configuration, it's all Git config & CI/CD based.
API design and lifecycle management is another place where you'll definitely want robust tooling since writing Swagger specs by hand gets cumbersome and right quick. Fortunately there is a large variety already available to fulfill not just the design phase but many other roles as well. Take a look at
https://openapi.tools/ for OpenAPI / Swagger tooling (for RAML my understanding is that it's the go-to option only in case you've chosen Mulesoft which provides a high degree of integrated tooling as part of the enterprise subscription).
Another essential tooling aspect is interface layer code generation based on the API - both for the service and for consumers separately. Since I promote explicitly creating the API spec first, it would be unnecessary duplication to write the same interface descriptions in your selected language of choice by hand when you can just generate the method stubs with requisite annotations / attributes / configuration from the spec (terminology here is language dependent). Same applies (and more acutely) for the consumer side. Easy code generation is an important factor in creating the governance practices to mandate which parts of the API spec are mandatory to enable easy usage and thus good DX.
Warning on anti-patterns of shared binary libraries
One common anti-pattern for helping customer teams consume the service's API is by providing them domain or service customized binary library. At first glance this may seem very sensible - provide re-usability and reduce the need for duplication at consumer side. The problem of the approach is that it creates a binary dependency between teams forcing binary dependency updates which very easily cause breaking changes. One of the main aims of microservice architectures is to reduce coupling between teams and the binary libraries directly break this by increasing coupling.
You could say that there are ways to minimize the downsides e.g. by keeping all logic out of the library but the domain logic has a tendency to swim in when it has an avenue. The library also easily becomes a point of blame making responsibility less explicit since now the service of one team (team is supposed to have total ownership of its service) has another team's code running within and potentially causing trouble.
Yet another problem is that a library usually needs to be provided for a specific language and in a large polyglot corporate environment this means that many teams will have issues.
When using REST and non-strict field binding then often the APIs can be improved without breaking - and this too is easily made more challenging via shared libraries which may need the consumer applications to be rebuilt to get a new version of the library (yet more coupling).
So in short, just don't do it unless you have an extremely good reason and rationale (of which a well known example is Netflix which has different scaling requirements compared to most corporate environments). Googling on the topic left up to you.
Mock data & mock server tools
An important part of governance is mandating providing sufficient mock data in the API specification itself. This is extremely valuable for multiple reasons:
- It's automatic test data immediately
- Provides useful test data for consumers to use speeding up development using the API
- Provides ability to create generic sandboxes within dev portal or via API gws
- Acts as additional concrete example based documentation
There are tools available both for creating the mock data and incorporating it within the API spec and also for creating local service instances from the API specs that respond with real results based on the incorporated mock data.
Word on what was left unsaid
Internal API ecosystem governance model was mentioned several times but I'm still developing my views on so I'll leave a deeper look for another time.
REST / HTTP/json wasn't mentioned at all in the context of API First since at the principal and generic tooling level it isn't actually essential. HTTP/json (and hopefully RESTful) services are increasingly the de factor standard though and it's the industry wide trend so I don't see any point in fighting against it unless you have specific needs regarding extremely low latency or high throughput in which case it's very useful looking at protocols like gRPC to standardize on.
There is much more to internal and external API ecosystems but hopefully this provides you with some understanding on what might be gained by looking improving existing ESB based integration architectures and how to structure development team responsibilities for maximum productivity.
![[IMG]](https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhRUsPSkS_P0S6dK3lvVZ8DTmC695oAdcN1Xf5CFhG-RcfbNzvs90LuHZYGf_4Y2RQ3bFJMCNZdyMJEObr6Xr8B7MQb2D4YtjLbr1-3XgwM8EYY7I1mpUPRnlFRZSNdtY9tglmV6RwHhmV6/s320/coneOfTestAutomation.png)
![[IMG]](https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgJBhcYmTaOrRoBaFLFHhQqVhSxqGGKGgbUDvlH24IWP3wD0TE3_ByiAPBTwAW8VEn_t16eicUfAZCioxWwJ1Mk7zSRlYWerzi-UKRArE0ulWWkkjiU_Sp-IzAimidnCkgnP-p5Q3L050w3/s320/pyramidOfTestAutomation.png)
