Kin Lane, API Evangelist






API Evangelist Location API


API Lifecycle Workshop Presentation - Design

API Lifecycle - Design

  • → Definition
  • → Design
  • → Versioning
  • → Virtualization
  • → Testing
  • → Landing Page
  • → Documentation
  • → Support
  • → Communication
  • → Road Map
  • → Discovery

Definition

Using definitions as the center of the API design process, developing an OpenAPI contract for moving things through the design phase, iterating, evolving, and making sure the definitions drive the business goals behind each service.

Definition → Organization

The over-arching source control organization for each service, providing an umbrella for different development groups and projects, and governing who has access to each design.


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 → Repository

Leveraging source control repository for each service, providing a self-contained, shareable, forkable way to engage with a service. Allowing for EVERYTHING involved with a service to be accessed in a single location.


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 → README

The README for each services repository, providing an overview of the service, complete with all the relevant links to all the moving parts. Any user should be able to land on the README, and easily get up to speed on what a service delivers.


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 → Service Name

A simple title for each service, describing what it does in concise terms, providing a simple way for any internal or external part to learn about the value it offers.

Definition → Service Description

A simple, descriptive paragraph for each service. Providing less that 250 words about what value each service delivers. Avoid just writing the obvious, and describing what an API is, and focusing in on describing the value being delivered by each service.

Definition → Schema

JSON schema for the data behind service, providing a standalone JSON schema for use in other systems, applications, and services. Doing the heavy lifting of describing the objects, fields, types, and other technical details of the data behind each service.


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

An OpenAPI definition for the surface area of the API, providing a machine readable contract for what each service delivers, that can be used across the API lifecycle, guiding every aspect of delivering each service.


Tools:

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

Definition → Domain

Considering the domain that each service fits into and exploring the sphere of knowledge and activity around the domain each service is delivering value within, ensuring the the right definitions, vocabulary, and other elements are present at design time.


Links:


Elements:

  • Context - Describing the setting and meaning that 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 → Tags

Defining what tagging taxonomy will be applied across resources, for use in tagging across definitions, documentation, and infrastructure operations. Ensuring that APIs leave this stage of the lifecycle properly tagged for organization, indexing and discovery.

Definition → Assertions

Human and machine readable assertions of what service does, leveraging the existing JSON schema, and translating that into business objectives, asserting that a service does what it is supposed to--providing a simple bulleted list explaining what is expected of a service.

Definition → Scenarios

Providing machine readable definitions that provide the mappings and business rules for orchestrations, scenarios, and other automated processes associated with a service, for use as part of testing, monitoring, security, and other automated functionality.

Definition → Team

A list of team members for the service, providing a nice list of who is responsible for designing the relevant business contract that will be needed to move a service from design to production.

Definition → Export Contract

Ensuring that all contracts and artifacts are exported as part of the design area of the lifecycle, making it available for use across development and production stages.


Design

Considering the overall approach to design for all APIs, executing upon design patterns that are in use to consistently deliver services across teams. Leveraging a common set of patterns that can be used across services, beginning with REST, but also eventually allowing the leveraging of hypermedia, GraphQL, and other patterns when it comes to the deliver of services.


Services:

  • Stoplight.io - StopLight, providing engineering teams with the best way to document, test, and build web APIs.

Tools:

  • API Stylebook - An aggregate of API design style guides from different companies.
  • Swagger Editor - An editor for OpenAPI from SmartBear Swagger.
  • OpenAPI GUI - A GUI API design editor for working with OpenAPI.
  • Apicurio - A GUI API design editor for working with OpenAPI.

Links:

Design → Base Path

Defining the part of the API path that goes after the host, and before each path, and is constant across all endpoints for each service.

Design → Path(s)

The paths that are used to define each individual API resource, providing a plain language description of a resource, with a meaningful, logical, structured path for accessing each individual resource.

Design → Verb(s)

The HTTP verbs used for each service, including GET, POST, PUT, and DELETE, but also leverage other HTTP verbs when relevant.


Links:

Design → Parameters

The query parameters that are used by each service, as described by the OpenAPI. Providing a list of parameters that can be used to define the API request dimensions that are available for a service.

Design → Headers

Logically using HTTP headers by each service, as described by the OpenAPI, properly leveraging the web when it comes to the transport of all resources.


Links:

Design → Body

Usage of the body as part of API requests as opposed to parameters, or in parallel to. Is the body used for POST, PUT, and other variations to help manage the payload?

Design → Beyond Verbs With Actions

Consistently defining how actions will be designed beyond the usage of the common HTTP verbs, having a set of design patterns for addressing actions made across all resources.


Links:

Design → Media Types

Quantifying the media types that are used by each service, as described by the OpenAPI. Provide multiple representations of a resource, allowing the consumer to negotiate the type of content.


Tools:


Links:

Design → Hypermedia

Emulating the patterns present in the web, and leverage existing hypermedia types to make APIs more resilient, evolvable, and flexible when it comes to client integration.


Tools:

  • JSON API - JSON API is a specification for how a client should request that resources be fetched or modified, and how a server should respond to those requests.
  • HAL - HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API.

Links:

Design → Status Codes

Defining the HTTP status codes that are used by each service, as described by the OpenAPI. Leveraging the web to help understand what a service is doing at scale, as part of automated integration and consumption of a service.


Tools:

Design → Filtering

Allowing for the filtering of data returned as part of responses, leveraging paths, parameters, and other API building blocks to filter the responses a consumer will actually see.


Links:

Design → Pagination

Defining the pagination used by each service, providing the ability to break large responses down into smaller more manageable chunks across al resources in a consistent way by clients.


Links:

Design → Sorting

The sorting used by each service, allowing consumers to sort the responses they see and define what the order of data will be when consuming API resources.


Links:

Design → Response(s)

The responses that are used by each service, as described by the OpenAPI. Providing details regarding the response, and referencing the schema being returned as part of the response.


Tools:

  • OpenAPI Response Object - Describes a single response from an API Operation, including design-time, static links to operations based on the response.

Design → Errors

Defining a structure for error handling that leverages HTTP status codes, but goes further with a common schema definition.


Tools:

  • Problem Details for HTTP APIs - This document defines a "problem detail" as a way to carry machine-readable details of errors in a HTTP response to avoid the need to define new error response formats for HTTP APIs.

Links:


Versioning

Managing the definition of each API contract being defined as part of the API design stop for this area of the lifecycle, and having a coherent approach to laying out next steps.

Versioning → Major

Define the major release for each service.

Versioning → Minor

Define the minor release for each service.

Versioning → Road Map

Making sure there is a road map definition for each version of a service.

Versioning → Communication

Ensuring there is a strategy for communicating with all stakeholders around the release.


Virtualization

Providing mocked, sandbox, and virtualized instances of APIs and other data for understanding what an API does, helping provide an instance of an API that reflects exactly how it should behave in a production environment.


Links:

Virtualization → Paths

Considering offering mock API paths for use by integrators, providing production-like instances of the API to use, and play with to provide feedback on API services.


Services:

  • Mockable - Mockable is a simple configurable service to mock out RESTful API or SOAP web-services. Reply with static or dynamic JSON or XML Payload.
  • MockLab - Rapidly simulate APIs for faster parallel development and more comprehensive testing

Tools:

  • Prism - Supercharge any OAS file with mocking, transformations, validations, and more.
  • API Sprout - A simple, quick, cross-platform API mock server that returns examples specified in an API description document.

Virtualization → Data

Considering offering synthetic data for use by integrators, helping ensure virtualized APIs provide as production like experience in a virtualized way.


Tools:

  • Synthea - Synthea is an open-source, synthetic patient generator that models the medical history of synthetic patients.

Testing

Going beyond just testing, and making sure that a service is being tested at a granular level, using schema for validation, and making sure each service is doing exactly what it should, and nothing more.


Services:

  • Stoplight.io - StopLight, providing engineering teams with the best way to document, test, and build web APIs.

Links:

Testing → Scenarios

The scenarios for testing each service.

Testing → Saved Requests

Save specific requests from a service to be used in testing.

Testing → Responses

Save specific responses from a service to be used in testing.

Testing → Playback

Allowing requests to be played back, based upon history.

Testing → Results Archive

The results of assertions tested against each service, providing a history of all tests.

Testing → Reporting

Having a strategy for reporting from testing that is occurring.


Landing Page

Making sure that each individual service being designed has a landing page for accessing it's documentation, and other elements during the design phase.

Landing Page → Hosting

Information about the hosting service used for this portal.


Tools:

  • Github Pages - Hosted as a static Jekyll site as part of the GitHub repository for the service.
  • Stoplight.io - StopLight, providing engineering teams with the best way to document, test, and build web APIs.

Landing Page → Template

Information regarding the UI template used for this portal.


Tools:

  • HTML5 Up - A HTML, CSS, and JavaScript Jekyll template.

Landing Page → Discovery

Ensure that each services landing page is discoverable through the design phase.


Documentation

Ensuring that there is always comprehensive, up to date, and if possible interactive API documentation available for all APIs being designed, allowing all stakeholders to easily understand what an API is going to accomplish.


Services:

  • Stoplight.io - StopLight, providing engineering teams with the best way to document, test, and build web APIs.

Links:

Documentation → Paths

Documenting the API paths that are available for each service.

Documentation → Schema

The descriptive header and footer paragraphs for the documentation schema.

Documentation → Examples

Examples of using the API path for each service.

Documentation → Definitions

Links to the machine readable API definitions for use as part of each service.

Documentation → Errors

Details about the errors encountered using each service, including status codes, and messages.


Support

Ensuring there are support channels available for an API, and stakeholders know who to contact when providing feedback and answering questions in real, or near real time, pushing forward the design process.


Links:

Support → Email

The email account(s) for supporting each service.

Support → GitHub Issues

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

Support → Tickets

Providing a ticketing system for submitting formal support requests as part of the design process.


Communication

Making sure there is a communication strategy for moving an API through the design phase, and making sure stakeholders are engaged as part of the process, with regular updates about what is happening.


Links:

Communication → Blog

The blog for each service.

Communication → Github

The Github account for each service.

Communication → Internal

Internal communication channel for each service, like Slack or other channel.

Communication → External

External communication channels for each service, like Slack or other channel.

Communication → Workshops

Conducting workshops to actively develop wider design practices.


Road Map

Providing a list of what is being worked on with each service being designed, and pushed forward, providing a common list for everyone involved to work from.


Links:

Road Map → Private

Providing an internal, private road map that design stakeholders can use to understand what is being designed.

Road Map → Public

Providing and publishing a road map (when applicable) that design stakeholders can use to understand what is being designed.

Road Map → Suggest

Provide a mechanism for users to make suggestions for the road map.


Discovery

Make sure all APIs are discoverable after they go through the design phase, ensuring each type of API definition is up to date, and catalogs are updated as part of the process.

Discovery → API.json

Publish an API discovery document for indexing API operations.

Discovery → OpenAPI

Provide an OpenAPI definition for each individual service.

Discovery → Postman Collection

The Postman Collection for each individual service.

Discovery → Catalog

Keeping all definitions available in a central catalog after design time.



The End


By Kin Lane


@kinlane





Return To Main Page