Disintermediation. It’s a term we more often use when referring to the removal of intermediaries in economics from a supply chain. It’s how modern companies reduce liability and/or reduce costs. Rather than hiring employees in-house to do the work, they hire a sub-contracting company with different guiding principles. It may bemuse you to suggest: your API program is probably operating the same way. Different API teams + different guiding principles = different supply chains. Producing their own products. Products that must be compatible with one another. Your customer will insist upon it. Maybe not today, but they will when they begin to scale their application. Can you imagine if a Lego block supply chain was producing a disparate type of Lego block? What if you had a hundred Lego supply chains? A cohesive set of guiding principles is critical. For your API development teams, your “supply chains.” We’ve become so consumed with getting APIs out the door, getting our developer portal up, we’ve forgotten the most important thing. The human experience of our APIs. Of the app developer. And what app developer would want to use your APIs if they knew that two years down the road, they won’t be able to easily integrate your other supply chains?. Leah will be talking about the guiding principles that are key to the compatibility of your supply chains. And to the future loyalty to your API program.

1. Designing a future-
proof API program
Leah Tucker
Founder & Software Integration Engineer | {your}APIs

2. A brand is simply trust.
– Steve Jobs

3. Goal of an API program.
The goal of our API program should be to help our supply chains create the
most interoperable building blocks for the {x} brand.

4. Goal of an API program.
• Disintermediation—the elimination of intermediary agents from a supply chain
to reduce liability and prices.
• Supply chain—a system of organizations, people, activities, information, and
resources involved in moving a product or service from supplier to customer.
• APIs—the key building blocks supporting interoperability and design
modularity.
• Interoperability—the capability of a product or system to interact and function
with others.
Terms.

5. Non-Internet example of
disintermediated supply chains.

6. Non-Internet example of
disintermediated supply chains
• John Smith uses the Park Spot mobile application to buy a parking spot for his
recently deceased father’s immaculately maintained Chevy Suburban in the lot
of a trusted luxury hotel chain.
• Unbeknownst to John, the hotel chain sub-contracts to a nationwide valet
services chain that parks his car, and the valet services chain sub-contracts to a
towing services chain that (later) tows then sells his car.
A customer trusts the brand.

7. Non-Internet example of
disintermediated supply chains
Who's in charge of brand loyalty?
The luxury hotel
chain tells John
they have no
control over the
valet services
chain.
The valet services
chain tells John to
provide proof of
ownership of his
recently deceased
father’s vehicle.

8. Non-Internet example of
disintermediated supply chains
• Our principles remain embedded in the company’s culture and in everything we
do today.
• How likely is it that this customer would recommend the brand to a friend or
colleague?
• This customer has gone from a brand promoter to a detractor.
No principles extending across supply chains.

9. Internet example of
disintermediated supply chains.

10. Internet example of
disintermediated supply chains
• Big Customer A is threatening not to renew a web services contract with API Provider
X.
• The customer is using raw API calls for their API-driven application using 40 APIs of API
Provider X. All of which have differing data models, which Big Customer A says, forces
them to do massive conversions/transformations between API calls.
• Stated that their application has become too complex and costly to maintain—so
complex it slows the speed with which Big Customer A can release new features.
A customer trusts the brand.

11. Non-Internet example of
disintermediated supply chains
Who's in charge of brand loyalty?
API Provider X
says they have
no control over
the consistency
of their APIs.
API teams say
it’s not their
responsibility to
be consistent
with other
teams.

12. Internet example of
disintermediated supply chains
• We help developers build cutting-edge applications.
• How likely is it that this customer would recommend the brand to a friend or
colleague?
• This customer has gone from a brand promoter to a detractor.
No principles extending across supply chains.

13. The decentralized approach to data
architecture.

14. The decentralized approach to
data architecture.
• A product manager works with stakeholders to identify functional requirements.
• The team architect pre-models data elements using their team’s existing case
conventions for the request/response (e.g. camel case), creates new data properties
using existing team conventions, e.g. underscores or dashes, data input values, plural
or singular for array and non-arrays, data format, etc. Asks team for input on API
architecture (as needed) then creates the API specification.
• Architects and developers work with their product manager to create a product name.
Technical writer creates all documentation.
.Disintermediated supply chains.

15. Too many custom building blocks.

16. Too many custom building
blocks.
.Example of 3 supply chain silos.
Supply Chain A Supply Chain B Supply Chain C
departure_date:
type: string
required: true
description: The departure
date
departureDateTime:
type: string
required: true
description: The ISO 8601
departure date of the flight (in
YYYY-MM-DDThh:mm:ss).
departure-date-time:
type: string
required: true
description: ISO 8601 departure
date of the flight. Date format is
YYYY-MM-DDThhmmss.sss.

17. Too many custom building
blocks.
.Unnecessarily complicated integration.
Supply Chain A Supply Chain B Supply Chain C
• Call endpoint A with
departure_date
• Parse/store departure_date
from the response of endpoint
A
• Convert value for
departure_date to the format
for departureDateTime
• Pass departureDateTime to
endpoint B
• Parse/store departureDateTime
from the response of endpoint B
• Convert value for
departureDateTime to the
format for departure-date-time
• Pass departure-date-time to
endpoint C
Note: here is an example of a JSON
data conversion in Python.

18. Too many custom building
blocks.
.Slow to launch application features.
Supply Chain A Supply Chain B Supply Chain C
• Please wait while we retrieve
your results.
• (Trigger loading indicator for
the user.)
• Please wait while we retrieve
your results.
• (Trigger loading indicator for the
user.)
• (Display results to the user.)

19. "Deep thoughts" series.

20. Deep thoughts.
• Application developers need to write code to parse, extract and store our API output
in the programming language of their application.
• If no consistent set of data models, rules, or policies were applied across supply
chains, application developers wind-up stuck in data silos with immensely complex
workarounds, with no way to scale-up.
• If these endpoints have a different means of request authentication and
authorization. Ugh! So much pain, too many burdens. Loss of trust.
.We know that...

21. Anticipate 5 years into the
future.
• Your API program has 100 supply chains. Each is following their own conventions for
product names, endpoints, request authentication/authorization, data
properties/architecture, error handling, documentation—without any shared
principles for consumption.
• What will your developer portal look like? How likely is it that your customer would
recommend your company/brand/product/service to a friend or colleague?
.Imagine...

22. The community approach to data
architecture.

23. The community approach to
data architecture.
• A product manager works with stakeholders to identify functional requirements.
• The team architect chooses from shared data assets by business from API platform data
libraries to feed `departure_date_time` and its definition into their API specification.
• The team architect and technical writer work with data stewards of these shared assets to
add new common vocabulary and documentation (as needed).
• The team uses API Design Guide naming conventions to create a product name, among
other things.
• The technical writer uses standard interfaces (“templates”) to create remaining
documentation.
.Directly responsible supply chains.

24. The community approach to
data architecture.
• Data architecture is a set of models, rules, and policies that define how data is
captured, processed, and stored.
• Modern data architecture (MDA) is the “big data” approach to data processing and
storage—driven by common data domains, events and micro-services; centered
around a common business information model (BIM) that represents the business
data domains; and optimized for sharing data across systems, geographies and
organizations.
.Modern data architecture.

25. The community approach to
data architecture.
• Each line of business/domain consists of a data steward team that collaborates with
other domains.
• Your data steward teams should consist of: 1) a Subject Matter Expert (SME) for their
business semantics, 2) a Lead Design Architect to create/add data libraries, and 3) a
Lead Technical Writer to create/add documentation.
.Data stewards for each line of business.

26. The community approach to
data architecture.
• Use common data libraries for each line of business/industry you serve as a shared
data asset on your API platform.
• A common data library acts as an “include” file that points to your common
vocabulary—which can be fed into your API specification.
• This allows supply chains to use “collective” data modeling, reducing time-to-deploy,
and increasing data architecture consistency across supply chains—and re-usable
code for application developers’ API integrations.
.Shared data assets by business.

27. The community approach to
data architecture.
• Use common vocabulary for your shared data assets.
• Common vocabulary contains your business data model: data name, format, and
description—each contained within your common data libraries (shared data asset).
• Work with data steward teams to create new common vocabulary.
.Common vocabulary by business.

28. A standard approach to API
documentation.

29. A standard approach to
documentation.
• Provide your supply chains with “fill-in-the-blanks” specification templates for
documentation. E.g. RAML, Open API (Swagger), Blueprint, etc.
• This allows your teams to produce the right documentation required for "discovery"
and a consistent approach for customers consuming APIs on a developer portal.
.Standard interfaces (API specifications).

30. Document your design guidelines.

31. Document your design
guidelines.
• Provide your supply chains with an API Design Guide to document your conventions
and reduce the bottleneck with your data steward teams.
• Give them a document of your design guidelines—case conventions for the
request/response, product name, collection/resource name conventions, error
handling, etc.
.API Design Guide.

32. "Deep thoughts" series.

33. Deep thoughts.
• Our application developers can re-use existing code to parse, extract and store our API
output in the programming language of their application.
• We are using a consistent set of data models, rules, and policies across our supply
chains and that our application developers—at minimum—no longer need to write
code for conversions or complex workarounds—at best, can re-use existing code.
.We know that...

34. Anticipate 5 years into the
future.
• Your API program has 100 supply chains. Each is following a consistent set of
conventions for product names, endpoints, request authentication/authorization, data
properties/architecture, error handling, documentation.
• What will your developer portal look like? How likely is it that your customer would
recommend your company/brand/product/service to a friend or colleague?
.Imagine...

35. .
Questions.
• My name is Leah Tucker. I’m the Founder and Software Integration Engineer of
{your}APIs (www.yourapis.co). We work with companies to apply the modern data
architecture approach to API platforms.