Session Themes and Topics
- Theme: Increasing our technical capabilities to achieve our strategy
- Topic: APIs (+asset delivery)
Session Leaders
- Gergő Tisza (@Tgr)
Facilitator
Description
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
| Question | Significance: 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
- 13:30 - 13:40: Opening presentation
- Intro and context
- Session structure
- Clarify desired outcomes
- Present information from previous sessions
- 13:40 - 13:45: Break into random groups of 6-10 people
- 13:45 - 13:50: Discuss use cases
- 13:50 - 14:00: Discuss strengths and weaknesses of existing frameworks
- 14:00 - 14:15: Discuss what the new framework (frameworks?) should be
- 14:15 - 14:20: Discuss infrastructure impacts
- 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:
- T206072: Wikimedia Technical Conference 2018 Session - Determining use cases and requirements for the APIs that we build - should inform what the API use cases and requirements are
- T206059: Wikimedia Technical Conference 2018 Session - Choosing installation methods and environments for 3rd party users - should inform what the platform compatibility requirements are
- T206068: Wikimedia Technical Conference 2018 Session - Identifying the requirements and goals for dependency tracking and events - might inform what technical choices are available for APIs which use internal or external cache; might be informed by API technology choices if the dependency tracking system is itself an API
- T206082: Wikimedia Technical Conference 2018 Session - Architecting core: stand-alone services - should be informed on which APIs should be standalone services
- T206080: Wikimedia Technical Conference 2018 Session - Architecting core: layers/components/libraries - should be informed on what need (if any) APIs have to share code components with MediaWiki (e.g. same DB abstraction layer)
Resources:
- Services and narrow interfaces RfC
- Audiences position statement: Needs from APIs
- Platform team position statement: Simplifying the Wikimedia Foundation technology stack
- MediaWiki Platform (draft) Architecture Principles
- Sessions from previous conferences:
- T183313#3930040 DevSummit 2018: Evolving the MediaWiki Architecture
- API docs:
- Action API documentation
- REST API documentation (see also: alternative implementation plans back in 2014)
- Other APIs:
- GraphQL (see also GraphQL)
- OpenAPI
- RfCs / proposals for new APIs:
- Storage service / Content API (most but not all of that got implemented in RESTBase)
- T66214: Define an official thumb API
- T111588: RFC: API-driven web front-end
- T114596: [RFC] Method for bare page retrieval (e.g. render only / no skin)
- T130663: WIP RFC: Reference API requirements and options
- T140813: Protect sensitive user-related information with a UserData / auth / session service and T206010: RfC: Session storage service interface
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:
- ...
