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 that we're currently working on is available at the Knowledge Base repo.
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
This interview happened on January 30, 2023. These are the notes:
- When reviewing an API Design, the first thing he wants to see and understand is context.
- He wants to know about the use case and how the users would interact with the API.
- He also wants to know how the API would fit the bigger picture from a business perspective.
- Furthermore, he checks if the API follows a generic REST style, following all the known REST elements.
- He mentions that some of the elements are considered "standard."
- However, other elements can be controversial, e.g., pagination.
- He mentions again that context is the most important element. You need to understand the context around the API to understand the API Design patterns that matter and should be followed.
- He believes the most important thing about context is identifying how the API generates business value.
- He mentions regulations specific to certain contexts, and he would follow those regulations while reviewing an API Design.
- Furthermore, he would also go through internal company API Design Guidelines and "rules."
- Related to the data shape, he would go field by field and understand if the data model can be extended or if it's limiting the ability to grow its capabilities.
- He mentions that he would research and find what other people are doing. He would search for APIs that are similar to the one he's reviewing or designing.
- In his opinion, having a knowledge base would help him justify the reasons for his choice because it would help him provide valid references.
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.
- Persona name: Marianne Talbert
- Persona role: Technical Researcher
- Archetype: Explainer
- Analyze and interpret patterns and trends from existing technical data.
- Obtain summarized results from technical data to deliver in presentations.
- The R programming language.
- VS Code
- Jira
- Google Slides
- Zoom
- Share technical data with business stakeholders.
- Prove hypothesis to business stakeholders based on existing technical data.
- Persona name: Franklin Gregory
- Persona role: Staff API Designer
- Archetype: Designer
- Design APIs based on findings from user interviews.
- Incorporate industry best practices into API Design.
- VS Code
- Postman
- GitHub
- Zoom
- Validate API Design solutions with potential users and stakeholders.
- Identify API Design industry best practices.