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.
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.
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.
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.