Product Tech Steering Committee

From mediawiki.org
(Redirected from API Request Process)

NOTE this has now evolved as part of the Request Funnel Framework. The content on this page is considered stale.

This document describes a process within the Wikimedia Foundation that lets client developers easily request new APIs and systems to support their work.

Background[edit]

In July 2020, as part of the Product and Tech team collaboration annual plan, the Product and Platform departments formed a working group to improve cross-team collaboration with a focus on API initiatives. The group agreed on an objective to “define a process for aligning goals and assigning work for API development.” To achieve this objective, members identified the following four key results:  

  • KR1: We implement a process to prioritize and manage API development across teams
  • KR2: The workflow is mapped with a visualization
  • KR3: A Phabricator board set up to implement the process
  • KR4: Written learnings about the process in development.

This present document describes the process from the API pre-request to product delivery.

Scope[edit]

This process focuses on API initiative prioritization only. It does not cover any other product initiatives the Platform Engineering, Product Infrastructure and/or Architecture teams work on with the Product Department, which may fit into the suggested workflow but are outside the working group’s current mandate.

Goals[edit]

The goals of this process are to:

  • Have a transparent decision-making process for Product and Platform teams
  • Set timeframes for decision-making
  • Identify team representatives
  • Facilitate cross-team collaboration

Definitions[edit]

API[edit]

"An interface for other applications to send and receive information"

  • When requesting APIs in this process, this is very much the output on what's being delivered.
  • e.g. In order for us to display Top Read Articles in our app, we must send a request to the wikifeeds API

Capability[edit]

"The power or ability to do something"

  • When requesting APIs in this process, this refers to the outcome of what's being delivered.
  • e.g. Through the echo MediaWiki extension, we are able to provide the push-notification capability for all apps to use

Platform[edit]

"A set of reusable capabilities typically provided through APIs and other infrastructure"

  • As a main constraint to scale, we want to ensure we have platform(s) in place for
  • e.g. The Search Platform provides a set of search capabilities such as "search filtering" and "search suggestions" by through their APIs

Process  [edit]

Although there’s an oversight committee, the development and client teams work hand-in-hand throughout the process, iterating on specifications along the way.   We expect this process to evolve overtime.

0. Pre-Request Product Process[edit]

Who is responsible: Requesting team in partnership with platform

These are all steps that should happen prior to making an API request. It might be that, after following these steps, an API request is not made.

  1. Ideation
    • Coming up with an idea for a new feature for a front-end product
    • Timeframe: On your own schedule
    • Owner: Client Team
    • Example: “We think a good structured task would be to add recommended links to an article”
    • Resources needed: None
  2. Informal Design
    • Loose structuring of software components for realising the idea
    • Timeframe: 1 month before desired production usage
    • Owner: Client Team
    • Example: “I guess we’d need data on which links to recommend, and then we’d show that in the UI”
    • Resources needed: Informal consultation with API teams
  3. Review existing or planned for APIs
    • Try to satisfy requirements from existing APIs or APIs that are planned for/in development.
    • Timeframe: 1 month before desired production usage
    • Owner: Client Team
    • Example: “Doesn’t Growth do link recommendations? We should use the same API they do.”
    • Resources needed: API Catalog & Documentation, API Roadmap

1. API Request Made[edit]

The Product team submits an API initiative request by creating a Phabricator ticket in the Untriaged column on the Platform-Product Roadmap Workboard here, ideally no later than 3 months before stakeholders expect to start using the API to give the team responsible for building the API enough time to plan and execute. As stated earlier, the development and client teams work together to build the API, including frequent client reviews, feedback, and demos throughout the API initiative implementation.  

The Phabricator request ticket must include the timeline, vision, target groups, needs, products, API attributes, and aligned goals/OKRs in the description.

All steering committee members join the Tech-Product API Roadmap Phabricator project as watchers to receive notifications when other users make changes to the Phabricator workboard.

1a. Request Types

Keep in mind of the types of API requests to make below:

  • Net New API
    • Given there are no other APIs that have the same or similar functionality you're looking for, a Net New API request would be identifying the requirements
    • e.g. “For our new user badge feature, we’ll need a way to list the user’s existing badges, add a badge, get badge details, and remove a badge from their list.”
  • Pre-existing API add-on
    • See if you can adapt an existing API to serve purposes of the new feature. Keep in mind that these requested changes need to be backwards compatible as not to break any of the existing consumers
    • e.g. “This recommendations API works OK, but for Android we’d need have a timestamp on each result.”
  • Build vs Buy
    • Decide whether the team should build the API on its own, or ask for another team to do it
    • e.g. I don't think our API will be used by anyone else, so it's most likely that we should built it

2. Initial review[edit]

As part of the initial review, Seve, API EMs or Tech Leads, and the Client team representative (ideally Product Manager or Tech Lead) review the request to clarify and open questions and issues that have an impact on prioritization. This might include things like scope boundaries, security, performance, and anything that might be affected by this being implemented. The outcome of the initial review is that Seve understands what is being asked of and can call out any known red flags or areas of concern. Once the card has been reviewed, the ticket will be moved from the “Untriaged” column to the “Reviewed” column ready for prioritization and team assignment.

3. Prioritization and Team Assignment[edit]

The following will be part of the steering committee in order to make the decision on how to move from the “Reviewed” column to one of the “Later”, “Now” or “Next” columns.

  • Seve Kim
  • Desiree Abad
  • Jon Katz
  • Danny Horn
  • Will Doran
  • Mat Nadrofsky
  • Optional: Client Team representative
  • Optional: OKAPI team representative
  • Optional: Architecture team representative

In order to make the decision to prioritize on the upcoming roadmap, the following are a non-exhaustive list of criteria that is considered:

  • What is the client timeframe?
  • What is the size of the API (endpoints)?
  • How many client teams need this API?
  • What is client priority? What is the departmental priority?
  • Is the API reusable by internal or external teams?
  • Is there a team available to build this?
  • Do we have skills to build the API?
  • What is the level of risk?
  • Why should we work on this next?
  • Why should we work on this later?  

In addition to establishing what the priority of the work is, the team selection for who will do the work needs to be decided on. In the process of selecting the team to take on this work, the skill sets, team capacity and knowledge also needs to be taken into account.

As in most cases, either the Platform Engineering team or Product Infrastructure will be first considered for the work. There is no hard and fast rule between whether work should be given to either of these teams and the hope is that a more defined boundary emerges over time. Depending on the some of the considerations when selecting the team, a few example cases are:

Architecture Proof of Concept[edit]

If there is an architecture proof of concept, it is most likely to have the Architecture team be slated to commit to the work.

Potential Commercial Usage[edit]

If there are aspects in which the API could have commercial usage, the OKAPI team could be best to take development on.

Client-Specific[edit]

A front-end team, such as Android, could be best to maintain ownership over services that are uniquely geared towards their mobile platform.

Team Familiarity[edit]

The team being considered has shipped something similar before or has high familiarity with the existing technology or interface.

ML?[edit]

Other artifacts that can be leveraged in the team selection process:

  • Phabricator board
  • Product Infrastructure skills matrix
  • Platform Engineering skills matrix
  • Architecture skills matrix
  • Security skills matrix
  • Platform skills matrix.

4. Handshake[edit]

Once the steering committee has decided on the request of the API, the slated team will circle back the client team that submitted the request to align on timeline, scope and “shake hands” to get agreement on what outcome the client team expects.

Coming out of this meeting, the expectations are that a written specification is agreed upon by both parties, client and platform alike. In the event of a prototype, then there should be explicit success metrics required that signify this API should be continually maintained. Likewise, there could also be conversations in this meeting around system architectural upgrades.

5. Principles on Collaboration[edit]

At this point, both client team & tech team move forward with their process. The expectation on how teams collaborate are supported by the following principles:

Continuous Communication[edit]

Clients and API teams are expected to meet, communicate and stay updated on a regular basis. Any changes to the specifications or requirements should be brought up as early as possible in order to reduce the impact of changes needing to be made.

Strive for Self-Service[edit]

In order to ensure autonomy and streamlined implementation for the Client Teams, APIs should be easy to use without being dependent on API teams for help or clarification. This means having an understandable API with clearly named endpoints, all documented with examples.

API Teams Own Reporting & Dependencies[edit]

API teams should own and drive the progress against the agreed upon timeline and deadlines. Updates as to release notes and versioning changes should be coming from those teams. Likewise, the API teams are accountable for running all relevant issues past security, performance and legal (often in coordination with the Client Team).

Consider the Whole Lifecycle[edit]

As the work is starting to take shape, there should be a strong lean towards non-proliferation of APIs. There should be thought in whether existing APIs can be extended to meet new use cases. Also, considering if new use cases aren’t met by old APIs, thus planning for deprecating entirely.

Warranty[edit]

Should there be any problems and requested changes needed post-deployment, there should be an agreed upon support buffer that the API teams should be providing in a set time.

Process Visualization[edit]

API Request Steering Process Flow

The process flow below articulates the entry and various exit points along with how work flows through our process at a high level.

FAQ[edit]

  • What constitutes as a valid "API request" for this process?
    • Any request that has an expected outcome to a problem is valid. The solution, however, can be an existing API, a net new API, deference to an appropriate team that has a solution, or a combination.

Activity[edit]

We publish meeting minutes weekly, providing information about the committee's activities.


See /Minutes. See /Processes for the facilitation guide.

Open Questions[edit]

  • How do we choose which team does the work? (e.g. Product Infrastructure or Platform Engineering?)
  • What are we not covering in this process and why?
  • How do we work with other teams? (e.g. Research, ML, etc.)
  • How are defining the ownership and ongoing maintenance of the things getting built?
  • Is this an interim solution or this is the indefinite right way to do this from now on?