Skip to content

API

Jump to bottom
Bruno Pedro edited this page Feb 24, 2023 · 32 revisions

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

image

  • 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.
Benefits
  • Obtaining quick access to vast amounts of API-related data.
  • Getting accurate, up-to-date, and reliable API-related information.
  • Comparing an API Design with the practice across verticals.
  • Retrieving reports of API-related statistics and insights.
Behaviors
  • Populate a spreadsheet with selected attributes of API-related data.
  • Share a report of API-related statistics.
  • Get the full definition of one or more APIs.
  • Get the similarities between two or more API definitions.
  • Obtain an API definition that is representative of a vertical.
Tools and services used
  • Spreadsheets, e.g., MS Excel or Google Sheets
  • The R programming language
  • VS Code
  • Postman Visualizer using d3js
  • HTML and JavaScript to render the data
  • Google Slides
Challenges
  • Share technical data with business stakeholders.
  • Prove hypothesis to business stakeholders based on existing technical data.

API Designer

image

  • 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.
Benefits
  • Comparing an API Design with the practice across verticals.
  • Obtaining reusable API Design patterns.
  • Retrieving reports of API-related statistics and insights.
  • Validating API Design options based on accurate data.
Behaviors
  • Identify and extract API Design patterns.
  • Share a report of API-related statistics.
  • Get the similarities between two or more API definitions.
  • Obtain an API definition that is representative of a vertical.
Tools and services used
  • VS Code
  • Postman
  • Confluence
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

image

  • 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.
Benefits
  • Obtaining API feature and version usage trends across verticals.
  • Retrieving reports of API-related statistics and insights.
  • Backing up product decisions with statistical API information.
Behaviors
  • Share a report of API-related statistics.
Tools and services used
  • Aha
  • Jira
  • Confluence
  • Web browser
  • ChatGPT
Challenges
  • Validate API Design solutions with potential users and stakeholders.
  • Decide what API standards and common practices to support in their product.

Technical Architect

image

  • 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.
Benefits
  • Obtaining API feature information across all existing APIs.
  • Comparing an API Design with the practice across verticals.
  • Retrieving reports of API-related statistics and insights.
Behaviors
  • Share a report of API-related statistics.
  • Get the similarities between two or more API definitions.
  • Obtain an API definition that is representative of a vertical.
Tools and services used
  • Postman
  • ABACUS
  • Confluence
  • ChatGPT
Challenges
  • Reuse existing APIs.
  • Know what APIs exist in the organization.
  • Understand the context behind the creation of an API.

Definition

Architectural style

The definition of the API architectural style is obtained by analyzing the support of the tools used by the personas. The following matrix outlines how each of the identified tools supports different architectural styles with a minimum of customization. Situations that require a specific custom solution are identified.

REST (GET) REST (POST) GraphQL gRPC SOAP
MS Excel ✔︎ VBA add-on ✔︎
Google Sheets ✔︎ add-on add-on
R ✔︎ ✔︎ ✔︎ ✔︎ ✔︎
Postman ✔︎ ✔︎ ✔︎ ✔︎
JavaScript ✔︎ ✔︎ ✔︎ ✔︎ ✔︎
Jira add-on add-on add-on
Aha Zapier Zapier
Web Browser ✔︎ HTML forms GraphiQL
URL ✔︎ limited

It's clear that the architectural style that better adapts to all the tools is REST (GET). GraphQL can also be a possible choice. However, sharing API requests via a URL has a length limitation. REST (POST) also seems like a good candidate. However, working with it on a Web Browser requires custom development.

Resources

API Definition

Personas
  • Researcher
  • API Designer
  • Technical Architect
Behaviors
  • Get the full definition of one or more APIs.
  • Get the similarities between two or more API definitions.
  • Obtain an API definition that is representative of a vertical.
JTBD
  • Find similarities between API Designs.
  • Enrich statistics by looking at particular API definitions.
  • Retrieve particular elements of several or a single OpenAPI document.
  • 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 the Design of an API.
Benefits
  • Getting accurate, up-to-date, and reliable API-related information.
  • Comparing an API Design with the practice across verticals.

Statistic

Personas
  • Researcher
  • API Designer
  • Product Manager
  • Technical Architect
Behaviors
  • Share a report of API-related statistics.
JTBD
  • Present summarized API-related statistics and findings.
  • Understand how API-related statistical information evolves over time.
  • 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.
  • Make data-driven decisions to understand what API standards to support in a product.
  • Obtain knowledge about API-related trends.
  • Understand how API-related statistical information evolves over time.
  • Understand the use of API patterns and security-related features.
  • Create learning material from existing API-related statistics.
Benefits
  • Retrieving reports of API-related statistics and insights.
  • Backing up product decisions with statistical API information.
Clone this wiki locally