Category Archives: Products

Documentation Driven Development

Documentation Driven Development

At adopting a new and growing trend, “documentation driven development” via “swagger” and now the newly updated specification, “OpenAPI 3”.

Documentation driven development (DDD) is not something new (some of its earliest concepts date back to 2011), but up until recently it never had an officially accepted name, nor an industry standard for the world to agree upon. It is the process of describing an API’s endpoints and what it expects as a request and should respond with. This enables a front-end team to easily use an API within their apps and mock the response.

Documentation driven development boils down to a two high level and basic principles:

  • Design the API first, then build it
    • The API design must adhere to the OpenAPI Specification (formerly known as Swagger)
    • The yaml file can be broken up with swagger-chunk
    • The finished result of the API design should be a Yaml or JSON file
    • The actual API routes should be built on what is documented in the design
    • The client, eg the browser, should communicate with the API via a generated file, built from a tool such as swagger-code-gen
  • An endpoint not documented should not exist
    • A JavaScript front-end engineer using a generated DDD API access file should not look outside of this file to access the API
    • As all routes must be documented, any other routes can be seen as not required &/or dangerous

Adhering to DDD simultaneously increases development speed whilst solving a growing issue regarding how the front-end and back-end teams both build and communicate. Further more this is not limited to company cross-team dynamics but also expandable to cross-company communications.

Looking to the future

DDD has given us some very big gains as described, but what could the future look like and how do we aim to streamline this process yet further.

Currently the API design must be written in a single Yaml file. When the API gets bigger than trivial the need to break the file down into sizable chunks becomes a must, this is where swagger-chunk comes in. swagger-chunk allows the developer to write many smaller and managable Yaml files which swagger-chunk then combines together into one.

Swagger-chunk is one step in the right direction, but it can be easy to get lost in a myriad of similar looking files. Further more, designing an API does not nesasarily depend on skill of a developer if there were an alternative to writing pure Yaml chunks…. Enter openapi-gui.

Openapi-gui is a graphical user interface to building the API design. The API designer does not require anything more than a web browser and technical knowledge on what a RESTfull API should be and deliver. In laymans terms, the API design can now be realised by a skilled technical product owner


Automatic virtual hosts on dev machine

Genius bit of apache conf code is an automatic vhost conf setup.

With above in place, I can now place any folder in ‘/var/vhosts/’ and it will be automatically mapped to http://.dev

Only thing to do is place .dev in your hosts file.

If you are using a .htaccess file you will need to add a rewrite base to it, otherwise this wont work.

You can also use Acrylic DNS proxy and stick a wild card in its host file like:

Tell facebook to rescrape your web page

Like any page  preview system out there.. facebook cache’s the content of web sites. This is to improve the UX for the user sharing a page… faster service equals better service.

This is not so great though for the guys and girls who’s job it is to get great, rich and beautiful content on the sites and blogs we frequent during our daily time wasting rituals.

Much like Google’s webmaster tools however, Facebook have a page to wipe the cache of a given url..

Important note: Do not use protocol-less url’s for your og:image tags. Facebook cannot handle it yet.



A Decentralized Internet?

I believe that the internet is truly the most important invention the world has ever seen. It gives the world of knowledge to the masses and is not controlled by any one person.

The last remaining problem with the internet is that all traffic routes through internet servrice providers (ISP’s). Each and every single request you ever make to the world wide web at some point routes through your ISP, and ISP’s are controlled by whom?

ISP’s are the last blockade to true freedom of speech and knowledge.

I recently stumbled across something called Maidsafe.

Is this a solution?

Net Neutrality – Join the Internet Countdown

I cannot actually put script tags on blogger, but if i could i would.

“Telling everyone about the vote is a key part of winning real net neutrality. We need your help to do just that. If you use twitter, click “Join with Twitter” below, and you can sign up to tweet once a day from now until the vote, or just once right before the vote. It’s your choice. If you don’t have twitter, then sign up with your email and we’ll send you a list of different ways you can help.”

var _cd_options = { theme: ‘red’ };

Google links you might not have known existed…

So it seems that the most popular mobile phone handset these days is either run on Android or iOS. They both offer amazing time saving apps, they monitor our sleep they alert us of news events and remind us when our friends birthdays are… they also track us. They don’t just track us a little but they track us a lot, unless you actively restrict features on your handset they track almost everything we do with our handsets. Do all your students know that access to all their activity, from what they search on the internet to where they have physically been in the world is stored in a data centre and easily accessible…

Have a peak at this post for the links:

Hump day!

Referring to Wednesday as “hump day” is a fairly modern tradition in English. The term represents the idea that a week can be visualized as a mound or hill that a person climbs, with Wednesday typically being the middle or peak of the week. There is some disagreement over which day of the week should be the “hump,” since it varies depending on when a person works and how a week begins. There are other sources for negative associations with Wednesdays, and few holidays are regularly celebrated on this day….

Read more here:

Enjoy more of your free time:

About working too much and what you can do about it (well, if you’re a teacher that is)

In 2012 teachers worked a total of 325 million unpaid hours!

A big factor increasing these hours is report writing. Although there are some generic tools available to create reports these often produce non student specific reports which offer little insight to the people that matter… the parents and the students!

Read more: