API

The Knowledge Base API lets you access the information that is available on the database. See Postgres for more information on how information is structured and stored.

You can use the API to obtain information about any element present in an API definition. You can also use the API to interrogate the system and obtain answers. A list of the questions we're currently working on is available at the Knowledge Base repo.

Design

This section outlines the Design of the Knowledge Base API. The API Design follows the Strategy/Definition/Validation/Specification process.

flowchart LR
  style Ideation fill:#fdf2d1,stroke:#e8833a,stroke-width:2px,stroke-dasharray: 5 5
  style Strategy fill:#e8833a,color:#fff
  style Definition fill:#ac6363,color:#fff
  style v fill:#ac6363,color:#fff
  style Specification fill:#207868,color:#fff
  style Implementation fill:#cfeeeb,stroke:#207868,stroke-width:2px,stroke-dasharray: 5 5
  Ideation --> Strategy --> Definition --> v{Validation} --> Specification --> Implementation
  v -- not validated --> Definition

Loading

Strategy

Interviews

API Designer, on January 30, 2023

This is a summary of the interview:

• One of the tasks of an API Designer is to do reviews.
• API Design reviews start by understanding context.
• Context determines what API Design patterns matter and should be followed.
• Understanding if an API follows a generic REST style is important.
• Being able to know what elements aren't generic is important. An example is the pagination style.
• Knowing what other similar APIs are doing leads to better API Design reviews.
• Having valid references helps drive API Design review justification.
• A Knowledge Base would enable comparison analysis with APIs from other businesses in the same sector.

Researcher, on January 31, 2023

This is a summary of the interview:

• The researcher produces statistics related to large amounts of API-related data.
• It's important to know the answers to questions related to API Design and common practices.
• Comparing APIs to find similarities between Designs is important.
• Looking at particular API definitions is interesting.
• The list of used tools include spreadsheets, e.g., Excel, Google Sheets, or Airtable, to retrieve and render the data from the Knowledge Base.
• Postman and d3js are also possible ways of retrieving and rendering data.
• The retrieved data might be post-processed if needed.
• Results could be presented live on Web sites with high traffic.
• Being able to execute the same queries over time and compare results is important.
• Knowing the trust level of the data is important.

Technical Product Manager, on February 2, 2023

This is a summary of the interview:

• The Technical Product Manager makes data-driven decisions to understand what API standards to support in their product.
• Questions like "what percentage of APIs use a specific standard," and "how are standards and their versions used across different company segments" are important.
• Getting information about trends in the usage of API standards helps drive decisions on what features to build into the product.
• The list of used tools include Mixpanel, Segment, and Google Sheets. The goal is to be able to query and analyze data.
• The ability to ask direct open questions is interesting. However, knowing what questions other people are asking is also relevant.

Software Architect, on February 8, 2023

This is a summary of the interview:

• The Architect's work involves migrating APIs between infrastructure technologies, standards, and organizations.
• Being able to reuse APIs is an important challenge.
• Understanding where there is an overlap of features or duplication of APIs is a need.
• There's a big challenge in understanding the context behind the creation of each API.
• Things like patterns and security-related features would be interesting things to know more about.
• The list of tools used includes Postman and ABACUS.
• The Knowledge Base could provide information to help create learning material.
• Having information about API usage would be interesting. Knowing what APIs are "successful" would be helpful.

User Personas

This is a list of the Knowledge Base API personas. The goal of this list is to provide information on how to design the API, so it fulfills the use cases that users care about. By better understanding who the API potential users are, you'll be able to design the API around their specific use cases. The individual personas are built from an API-centric perspective and are to be refined by taking into account more accurate information retrieved from user interviews.

All pictures and names have been generated, and do not represent real people. Pictures have been generated by thispersondoesnotexist, and names have been generated by the fake name generator.

Researcher

• Persona name: Marianne Talbert
• Persona role: Technical Researcher
• Archetype: Explainer

Jobs to be done

• Produce statistics related to large amounts of API-related data.
• Find answers to questions related to API Design and standard practices.
• Find similarities between API Designs.
• Enrich statistics by looking at particular API definitions.
• Retrieve particular elements of several or a single OpenAPI document.
• Present summarized API-related statistics and findings.
• Understand how API-related statistical information evolves over time.

Tools and services used

• The R programming language.
• VS Code
• Jira
• Google Slides
• Zoom

Challenges

• Share technical data with business stakeholders.
• Prove hypothesis to business stakeholders based on existing technical data.

API Designer

• Persona name: Franklin Gregory
• Persona role: Staff API Designer
• Archetype: Designer

Jobs to be done

• Verify if an API follows a REST style standard across all available APIs.
• Search for APIs similar to the one being designed or reviewed.
• Understand the context around an API Design based on statistical data.
• Incorporate industry best practices into API Design.
• Justify the reasons behind API Design decisions based on statistical data.

Tools and services used

• VS Code
• Postman
• GitHub
• Zoom

Challenges

• Understand the context behind the creation of an API.
• Validate API Design solutions with potential users and stakeholders.
• Identify API Design industry best practices.

Product Manager

• Persona name: Steven Kelly
• Persona role: Technical Product Manager
• Archetype: Builder

Jobs to be done

• Make data-driven decisions to understand what API standards to support in a product.
• Obtain knowledge about API-related trends.
• Get information about specific features of API standards.
• Understand under which scenarios APIs use specific features.
• Know which industries use specific API standards, versions, and features.
• Obtain answers to API-related questions asked in a human-friendly way.
• Understand how API-related statistical information evolves over time.

Tools and services used

• Aha
• Jira
• Slack
• Confluence
• Zoom

Challenges

• Validate API Design solutions with potential users and stakeholders.
• Decide what API standards and common practices to support in their product.

Technical Architect

• Persona name: Thelma Sorenson
• Persona role: Software Architect
• Archetype: Builder and Explainer

Jobs to be done

• Ask questions related to certain features of APIs, e.g., pagination.
• Understand the use of API patterns and security-related features.
• Understand the context around the Design of an API.
• Create learning material from existing API-related statistics.
• Obtain usage information of existing APIs.
• Obtain answers to API-related questions asked in a human-friendly way.

Tools and services used

• Postman
• ABACUS
• Slack
• Confluence
• Zoom

Challenges

• Reuse existing APIs.
• Know what APIs exist in the organization.
• Understand the context behind the creation of an API.