Standardisation is of key importance. If we standardise, we live freely.
Do you remember the proliferation of mobile phone charger interfaces in the mid ‘00s and routinely asking your mates if they had that most simple but elusive item ‘a charger for a xxxx mobile phone’? Life has become simpler recently hasn’t it, it’s either an Android or an ‘i’ charger…sweet. We can all get along with our day to day business now and know we are living in a standardised phone charger world. This leads to one tangible thing, efficiency in our daily lives.
Communication needs standards more than phone chargers. Being capable of speaking the same language means frictionless business can happen. APIs are communication vehicles and they have suffered a similar standards fate over the past 20 years. From a concept with no standard to a concept with multiple standards, APIs have lived through the ‘charger’ identity crisis and now, thankfully we see it, the one common standard.
Our APIs can now be created and consumed using a common language, the OAS (Open API Specification). After RAML (the most significant other standard) decided to support the OAS initiative in April 2017, we knew the future was both certain and bright.
What does it mean for my API development? Simple really (unless you are in the low percentile of exceptions) strongly recommend that OAS is considered as the default specification to describe, produce and consume RESTful web services within your organisation.
That gives you a strong starting point. If your team come back with another standards suggestion, get them to viva their proposal using OAS as the benchmark and use a checklist to compare the offerings. Be secure in the knowledge that a lot of big hitters (most big hitters in fact) support OAS (IBM, Google etc.). I think you’ll find that the discussion will be short. If your API is public, that discussion just got shorter.
In fact, it’s almost required that OAS is used for public facing APIs from here on out. Open Banking is an example of a project where large industry wide convergence to OAS principles is happening. It makes sense, people who have not met and will never meet must be able to develop interfaces which work together, an industry standard for APIs is a certainty and the OAS is the one for RESTful APIs.
OAS comes with an insurance policy too, the most powerful of all policies in technology today, the online community. No limits, no ridiculous constraints and a conversation of millions. Issues will arise and will be overcome by this mass movement of talented advocates.
While APIs are not necessarily RESTful and interfaces and standards do change (think VGA to HDMI), if your job is about selecting the right horse for the race right now, think RESTful and think OAS. If there is a sure thing in life, this is it.
Step 1 – Make sure your swagger files are compliant with the Open API Specification standard and make sure all your APIs are consistent. Do this by getting static analysis of your swagger (OAS 2.0) definition file underway immediately. This means that you test your swagger file every time it changes and ensure that it is compliant with the Open API Specification and that it is testable and functionally robust. If you pass a poor Swagger file to a test team then you’re wasting time; reduce the feedback loop and get this right first. You can use our Swagger / OAS validator for free, just click here:
You can help! Please share this tool by clicking here:
Within seconds you will have a list of errors, warnings and useful suggestions for your dev team to work on to ensure your definition file is not just compliant but solid. This is the first step to RESTful API happiness. Please use the tool regularly and please share this useful tool with your network and let us know what your thoughts are.