Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Designing a Future-proof API Program

301 views

Published on

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.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

Designing a Future-proof API Program

  1. 1. Designing a future- proof API program Leah Tucker Founder & Software Integration Engineer | {your}APIs
  2. 2. A brand is simply trust. – Steve Jobs
  3. 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. 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. 5. Non-Internet example of disintermediated supply chains.
  6. 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. 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. 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. 9. Internet example of disintermediated supply chains.
  10. 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. 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. 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. 13. The decentralized approach to data architecture.
  14. 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. 15. Too many custom building blocks.
  16. 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. 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. 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. 19. "Deep thoughts" series.
  20. 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. 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. 22. The community approach to data architecture.
  23. 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. 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. 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. 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. 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. 28. A standard approach to API documentation.
  29. 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. 30. Document your design guidelines.
  31. 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. 32. "Deep thoughts" series.
  33. 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. 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. 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.

×