Topic on Talk:Wikimedia Engineering Architecture Principles

Some things maybe worth mentioning:

• interfaces should be written with ease of extensibility without B/C breaks in mind. (E.g. use an option array instead a list of arguments, return an associative array instead of a scalar.)
• APIs (or published data, more generally) should support the use case of history reconstruction, to the extent it is feasible. (E.g. think of all the reasons creating the edit dataset was hard.) The same generic principle is relevant to other use cases as well (e.g. page_props being hard to match to revisions), not sure how to articulate it. Data that gets exposed should always be versioned? (Not in the "schema version" sense, but individually.)

Re "ease of extensibility": We already have "our software architecture SHOULD be modular, with components exposing narrow interfaces, to allow components to be replaced and refactored while maintaining a stable interface towards other components as well as 3rd party extensions." Maybe we can add "Extension points MUST be clearly documented as such, and SHOULD be designed in a way that allows them to remain stable over time".

Re "history construction": I know what you mean, but I see no good way of phrasing this as a principle. Maybe "APIs SHOULD provide mechanisms that allow consistent data sets to be retrieved with multiple requests"? This would certainly be nice, but hard to do in general. This seems really aspirational...