Skip to content

API

Jump to bottom
Bruno Pedro edited this page Feb 8, 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 that 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.

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
  • Analyze and interpret patterns and trends from existing technical data.
  • Obtain summarized results from technical data to deliver in presentations.
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

image

  • Persona name: Franklin Gregory
  • Persona role: Staff API Designer
  • Archetype: Designer
Jobs to be done
  • Design APIs based on findings from user interviews.
  • Incorporate industry best practices into API Design.
Tools and services used
  • VS Code
  • Postman
  • GitHub
  • Zoom
Challenges
  • Validate API Design solutions with potential users and stakeholders.
  • Identify API Design industry best practices.
Clone this wiki locally