Page MenuHomePhabricator

Wikimedia Technical Conference 2018 Session - Choosing the technologies to build our APIs
Closed, ResolvedPublic


Session Themes and Topics

  • Theme: Increasing our technical capabilities to achieve our strategy
  • Topic: APIs (+asset delivery)

Session Leaders

  • Gergő Tisza (@Tgr)



This session will delve into the action API, REST API, and any alternative solutions to answer open questions so that the API architecture can be resolved.

Questions to answer during this session

QuestionSignificance: Why is this question important? What is blocked by it remaining unanswered?
What are the use cases and requirements (client, infrastructure and platform) for Wikimedia and MediaWiki APIs? (This is expected to just summarize input from other sources - most notably T206072, T206059 and ops)Blocks answering the main question - the choice of technology must be guided by stakeholder needs. The answers should mostly come from other sessions (Applying the MediaWiki Platform Architecture Principles, Determining use cases and requirements for the APIs that we build, Choosing installation methods and environments for 3rd party users) and are just restated at the beginning of the session.
Take stock of the API frameworks (existing ones & promising alternatives, if any). What are their strengths and weaknesses? Which use cases and requirements can they effectively fulfill, and which not? What are their infrastructure needs and costs?Blocks answering the main question - to make an informed choice we must have an informed understanding of each option.
What should the future of our APIs look like? Should we standardize on a single framework? (Which one?) Or should we aim for a microservice infrastructure with full freedom of implementation? What of the legacy API modules? What of the “custom” APIs like ORES or WDQS?The answer to this question determines how investment into API development in the next several years should look like.
Given the above, what is the impact on system architecture, caching infrastructure and storage infrastructure?The outcome of the session should be suitable to inform infrastructure planning, and the architecture discussions on day 4.

Facilitator and Scribe notes

Facilitator reminders

Session Structure

  1. 13:30 - 13:40: Opening presentation
    1. Intro and context
    2. Session structure
    3. Clarify desired outcomes
    4. Present information from previous sessions
  2. 13:40 - 13:45: Break into random groups of 6-10 people
  3. 13:45 - 13:50: Discuss use cases
  4. 13:50 - 14:00: Discuss strengths and weaknesses of existing frameworks
  5. 14:00 - 14:15: Discuss what the new framework (frameworks?) should be
  6. 14:15 - 14:20: Discuss infrastructure impacts
  7. 14:20 - 14:30: Swap half of the groups, compare results

For steps 5 and 6:

  • Decide whether there is (mostly) agreement or disagreement
  • Decide whether there is more need for discussion on the topic, and how urgent or important that is.
  • Identify any open questions that need answering from others, and from who (product, ops, etc)
  • Decide who will drive the further discussion/decision process (ie: a four month deadline)

Guide for step 4

(Subset of architecture principles; feel free to deviate.)

  • Software that interacts with users SHOULD provide consistent internationalization across platforms and follow accessibility guidelines.
  • Our software SHOULD provide extension points that empower the community with ways to develop workflows using scripting languages, and ensure safety and maintainability of custom scripts.
  • Public APIs of our services SHOULD be modeled around abstract use cases, not catering to a specific user interface.
  • Data we offer for re-use SHOULD use clearly specified, stable data schemas based on widely used open standards.
  • Software components SHOULD be designed to be reusable, and be published for re-use.
  • Software that exposes public interfaces for use by other software SHOULD be subject to release management with clear and consistent versioning. Any breaking changes to such interfaces then MUST be announced in a timely and predictable manner over relevant channels.
  • Any elements scheduled for removal from a stable public interface MUST be documented to be deprecated beforehand, and SHOULD be kept for for backwards compatibility for a reasonable time.
  • All code SHOULD be designed for testability.
  • Comprehensive documentation SHOULD be maintained along with the code.
  • MediaWiki SHOULD be easy to install and upgrade in a development environment.
  • The MediaWiki stack SHOULD be easy to deploy on standard hosting platforms.
  • Small MediaWiki instances SHOULD function in low-budget hosting environments.
  • Our software and infrastructure SHOULD be designed to be resilient against spikes in demand and failure of backend systems.
  • Services and APIs SHOULD be designed to allow the identification of read-only and read-write HTTP requests to optimize routing and caching.
  • System design and technology choice SHOULD aim to reduce operational overhead and the cost of change management.
  • Our software and infrastructure SHOULD be designed in such a way to prevent unauthorized access to sensitive information, and to minimize the the impact of individual components getting compromised.
  • Our system architecture SHOULD isolate components to reduce attack surface while minimizing system complexity.
  • Tools and processes SHOULD be designed to allow us to be responsive as well as proactive in ensuring security.
  • Our deployment infrastructure and dependency management SHOULD make it easy to keep system components up to date.
  • Our deployment infrastructure SHOULD make it easy to change configuration settings without disruption.

Session Dependencies:


Related tasks:

Session Leaders please:

  • Add more details to this task description.
  • Coordinate any pre-event discussions (here on Phab, IRC, email, hangout, etc).
  • Outline the plan for discussing this topic at the event.
  • Optionally, include what it will not try to solve.
  • Update this task with summaries of any pre-event discussions.
  • Include ways for people not attending to be involved in discussions before the event and afterwards.

Post-event Summary:

  • ...

Action items:

  • ...

Event Timeline

kchapman renamed this task from Wikimedia Technical Conference 2018 Session - What technologies do we need to build our APIs? to Wikimedia Technical Conference 2018 Session - Choosing the technologies to build our APIs.Oct 3 2018, 2:33 AM
debt added a subscriber: Tgr.
Tgr updated the task description. (Show Details)
debt added a subscriber: ITait.
Tgr updated the task description. (Show Details)

@Tgr: Resolving this task. If there is work left in this task, feel free to either set the status of this report back to "Open" via the Add Action...Change Status dropdown and associate an active project tag to this task, or create separate followup tasks. Thanks.