APIs are flipping simple

How APIs are just child blocks, semantic versioning and what major releases are

Model of an API

The API is the hole.

In reality the shape is not a triangle but a structure of data (X contains Y) and format of the data (Y should be a number with no decimal places).

If you are working with an API, you are creating the block, they are managing the hole.

When things change

Things can change in three ways with APIs:

  • PATCH — don’t change the shape
  • MINOR — change the shape a bit
  • MAJOR— completely change the shape

Don’t change the shape

This could be for things like performance improvements, small tweaks in method, or fixing simple bugs.

The short of it is that you will want to record that a change has happened (so it is easier for bug fixing) but to your users nothing has changed.

There was a bug. We patched it.

Change the shape a bit

Sometimes you may want to change the shape a bit, usually to add a new optional feature. This means that it is backwards compatible; if you use the old shape it will still work.

New feature! Rounded triangles will now work.

Note: I know the image here shows a rounded triangle which would have worked otherwise. It is a limitation of the child blocks idea. You could imagine them as wire shapes, but I think that is a bit much…

Completely change the shape

In API development, there will come a time when you will need to complete change an API, and maybe sunset (stop people using) the old shape too.

This is done with a major release. You specify a new shape, which may be similar and may give the similar results — but in a very different way.

These are not backwards compatible — if you throw your triangle at the hole it will not go through.

If we threw a triangle at v2.0.0, it would not get through.

Great, so what.

Well you now know something called Semantic versioning. Oh, and you start to realize why good documentation is important — because you need to know the shape and types of data.

With this in mind you can start to see that APIs make software development strategy to be more like playing with LEGO blocks.

Knowing the shapes each require you can start understanding the complexity of adding new features that are powered by APIs as from the docs you can learn their shape.

Founder of EveryHour.xyz and Product Owner @ dunnhumby; just genuinely interested in a lot of things. Built racecars, built electronics, now building software

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store