Jeremy Glassenberg - Automating the API Product Lifecycle

API the Docs Virtual Event Series 2020 Recap

This talk was presented at API The Docs Virtual 2020 event series on 7 October. We are honored to share the video recording, slide deck, and talk summary below. Enjoy!

Visit the API The Docs 2020 recaps overview to explore all presentations this year.

Jeremy Glassenberg

Product & Platform (API) Leader at Deserve

Jeremy's presentation(video recording)



Jeremy's slides



We can go beyond generating API documentation of OpenAPI schemas, but to successfully utilize innovative solutions, you have to follow the path of the API Product lifecycle.

Early days of APIs

In 2008, REST APIs were rough and based on XML. They seemed simple to implement, but they weren't implemented well, partially because we didn’t have standards well adapted.

Having a schema in Web Application Description Language (WADL) you were able to auto-generate documentation. It was like a standard of how to design REST APIs in XML. WADL didn’t get popular, because using XML was inconvenient.

JSON pushed XML APIs off the scene, and Swagger brought the standard definitions: a schema. Now you can auto-generate RESTful API documentation from a swagger/OpenAPI specification file.

REST APIs became easier to build, fairly consistent, and aggregator tools make it possible to connect APIs.

API Product lifecycle

The failure of Product management, in general, is the philosophy of “If you build it, they will come…”

API Product cycle (CI/CD tech stack): automation to generate good content and make it easier to provide updates to the APIs, API documentation, API libraries, SDKs on the developer portal. To get even the smallest updates automatically reflected, you first have to create a solid design: start with the OpenAPI schema and build from there.

Identify the problem

  • Determine value points and use cases
  • Understand your customers: what problems does the developer community have? What are your partners trying to build?

Research to understand the problem

  • Establish high-level architecture
  • Come up with the right solutions for your partners: How to make it as easy as possible to build what they want?
  • What can be the solution? Schema.org, GraphQL, or REST?

Design

  • Create a schema definition for the API
  • Use IDEs to write and validate your OpenAPI schema

Implement -- if and after you have the OpenAPI schema

  • Build the API
  • Gateways:
    • want to accommodate OpenAPIs more
    • know how to set up the proxy-structure, what are the end-points or errors are going to be -- the gateway can handle some of the errors
  • Schema + Gateway = make it easier to build and launch the API

Launch the API and have an elegant Developer experience

  • Nicely looking, well-designed Documentation
  • API libraries
  • SDKs
  • Mock servers to let developers interact with APIs using test data
  • Developer portal

Maintain & Iterate

  • Manage the developer community
  • Developer Relationship Management
  • API monitoring.

What comes next to make APIs better

obvious iterations and opportunities

  • Auto-generate end-points from the models of the OpenAPI schema
  • Visually planning OpenAPI schema: using mapping-tools to visualize how your API should work
  • Developer portal solutions beyond documentation: automate the management of your App marketplace
  • Create a mapping between the OpenAPI and your database schema, and generate server-side codes that make queries to your database
  • Better monitoring and logging tools integrating with customer service solutions to improve customer and developer experience
  • Developer Relationship Management (DRM) as a business

Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.