Kin Lane, API Evangelist






API Evangelist Location API


API Lifecycle Workshop Presentation - Discovery

API Lifecycle - Discovery

  • → Low Hanging Fruit
  • → Discovery
  • → Communication
  • → Definition
  • → Dependencies
  • → Support

Low Hanging Fruit

Understanding what resources are already on the public websites, and applications, by spidering existing domains looking for data assets that should be delivered as API resources.

Low Hanging Fruit → Spreadsheets

Identify all of the XML files that are published across any domains.

Low Hanging Fruit → CSV

Identify all of the CSV files that have been published within any domains.

Low Hanging Fruit → XML

Identify all of the XML files that have been published within any domains.

Low Hanging Fruit → JSON

Identify all of the JSON files that have been published within any domains.

Low Hanging Fruit → Tables

Identify all of the HTML tables that have been published within any domains.


Discovery

Actively looking for web services and APIs that exist across an organization, industry, or any other defined landscape. Documenting, aggregating, and evolving what is available about each API, while also publishing back out and making available relevant teams.

Discovery → WSDL

Looking for WSDL documents across an organization.

Discovery → API.json

Looking for APIs.json files across an organization.

Discovery → OpenAPI

Looking for OpenAPI files across an organization.

Discovery → Postman Collection

Looking for Postman Collections across an organization.

Discovery → HTML

Looking for HTML service and API documents across an organization.

Discovery → .HAR

Looking for evidence of APIs from .HAR files tht are gathered.

Discovery → Logs

Looking for evidence of APIs from log files tht are gathered.


Communication

Having a strategy for reaching out to teams and engaging with them around API discovery, helping the remember to register and define their APIs as part of wider strategy.


Links:

Communication → Email

Use email to coordinate with other groups.

Communication → Meetings

Having regular meetings to discuss where APIs are.

Communication → Workshops

Conducting workshops to actively develop wider discovery practices.


Definition

Work to make ensure that all definitions are being aggregated as part of the process so that they can be evolved and moved forward into design, development and production--investing in all of the artifacts that will be needed down the road.

Definition → Organization

Defining the organizational structure, group, or other bounded context for organization definitions into.


Services:

  • GitHub - GitHub Inc. is a web-based hosting service for version control using Git, used for distributed version control and source code management functionality of Git.
  • GitLab - GitLab is a web-based Git-repository manager with wiki, issue-tracking and CI/CD pipeline features.
  • Bitbucket - Bitbucket is a web-based version control repository hosting service for source code and development projects that use either Mercurial or Git revision control systems.

Links:

Definition → Schema

Organizing individual schema assocated with a service, while also including it as part of the OpenAPI.


Tools:

  • JSON Schema - JSON Schema is a vocabulary that allows you to annotate and validate JSON documents.
  • JSON Schema Tools - A tool for managing JSON schema documents, and working with them to make sure they are complete.

Definition → OpenAPI

Producing an OpenAPI should be the central objective of the API discovery process, producing, then also evolving each API's definition throughout the lifecycle.


Tools:

  • OpenAPI - The OpenAPI specification for describing the surface area of the API.

Definition → Domain

Considering the domain that services fits into and exploring the sphere of knowledge and activity around the domain each service is delivering value within. Quantifying the service domain, helping decompose from a larger domain, and helping focus what each service does.


Links:


Elements:

  • Context - Describing the setting and meaning the defines the value of each service.
  • Model - The system of models used to define the elements of the domain each service.
  • Language - The vocabulary and language used to help articulate the value each service delivers.
  • Bounded Context - Describing the boundaries of where each service operates and delivers value.

Definition → Event Storming

Event storming is a rapid, lightweight, and underappreciated group modeling technique that is intense, fun, and useful for accelerating development teams.


Links:


Elements:

  • Domain Event - The event that occurs within the domain as part of a service execution.
  • Command - The trigger for the domain event occurring, setting it into motion.
  • Actor - Defining who executes command to trigger event, and is making things happen.
  • Aggregates - Aggregates logically group various commands, events, and reactions together.

Definition → Vocabulary

Organizing the common vocabulary in use across services, and APIs, establishing a single place to find the language used across domains.

Definition → Tags

Defining what the tagging taxonomy will be for applying across resources, for use in tagging across definitions, documentation, and infrastructure operations.

Definition → Team(s)

Map out all of the individuals being engaged as part of the service and API discovery process, and grouping them by team, group, or other organizational structure.

Definition → Catalog

Establish a central way to track on all API definitions that are being organized, from a folder on network drive, to GitHub, GitLab, or other CMS, with the object to eventually publish all usable definitions to a master catalog.


Dependencies

Defining any dependencies that are in play, and will play a role in operations. Auditing the stack behind any service as it is being discovered and documented as part of the overall effort.


Links:

Dependencies → Services

What existing services does a service depend on to do what it does, and would be impacted if something changes.

Dependencies → Software

What are the software libraries a service depends on for its operations, covering the code layer dependencies.

Dependencies → Data

What is the provenance of data being used as part of the service, and where are their continued dependencies.

Dependencies → People

What people is a service dependent on, requiring coordination, communication, and effort from individuals to move forward, and ensuring the right stakeholders are involved.

Dependencies → Organizations

What other organizations, internally or externally are required to move a service forward, making sure all stakeholders are considered.

Dependencies → Applications

Documenting the client applications depeendencies for a service, outlining who depends on the service based upon the applications they are using.


Support

Ensure that all teams have support when it comes to questions about web service and API discovery, helping them intially, as well as along the way, making sure all their APIs are accounted for, and indexed as part of discovery efforts.

Support → Email

The email account for supporting each service.

Support → GitHub Issues

Where to submit an issue to get support for each service.



The End


By Kin Lane


@kinlane





Return To Main Page