SOA proliferation through specification

James Earl Douglas

MediaWiki Developer Summit 2015

Thesis

Service development and consumption flourishes in a well-specified ecosystem.

Agenda

Background

Service-oriented architecture

Feature stew

See also: the join calculus

Composable units of functionality

Specification

Establish boundaries

Describe the interface

"To foo a bar, you must provide a baz, and you will receive a qux."

Specification formats

Swagger

http://wikimedia.github.io/restbase/v1/swagger.json

Examples

Swagger UI

http://wikimedia.github.io/restbase/

Swagger static documentation

http://wikimedia.github.io/restbase/v1/

Swagger client generation

var httpsync = require('httpsync');
var codegen  = require('swagger-js-codegen').CodeGen;
var fs       = require('fs');

var specUrl  = 'http://wikimedia.github.io/restbase/v1/swagger.json';
var response = httpsync.get(specUrl).end();
var swagger  = JSON.parse(response.data.toString());

var clientJs = codegen.getNodeCode({ className: 'RESTBase', swagger: swagger });
fs.writeFileSync('client.js', clientJs);

Swagger-generated client

var RESTBase = (function() {
    RESTBase.prototype.listRevisions     = function(parameters) { // ...
    RESTBase.prototype.getLatestFormat   = function(parameters) { // ...
    RESTBase.prototype.getFormatRevision = function(parameters) { // ...
    RESTBase.prototype.getFormatRevision = function(parameters) { // ...
    // ...
})();

exports.RESTBase = RESTBase;

Test automation

Swagger is extensible

"x-amples": [
  {
    "request": {
      "params": {
        "domain": "en.wikipedia.test.local",
        "title": "Foobar"
      }
    },
    "response": {
      "status": 200,
      "headers": {
        "content-type": "text/html;profile=mediawiki.org/specs/html/1.0.0"
      }
    }
  }
]

Roadmap

Where we're going

Happy users

Features delivered as desired.

Excited developers

Empowered to build and deliver awesomeness.

Rainbows and ponies for all

OMG!! Ponies!!

How we'll get there

Q) How do we stay on track?

A) Specify it.

Spec has to be reliable

Spec-first vs. spec-last

References

Discussion