Well, it’s an API dude, what were you expecting? Versioning sheesh, public-facing APIs are the one place you should be happy to stick with what you have and not get sparkly-eyed about newer releases. Well unless you REALLY need the service or endpoint v2 has to offer.
Public consumption APIs can’t really be improved in terms of soft-versioning (i.e minor updates), except in hacky ways like extra headers and query strings. If you screwed up on releasing your v1, well folks, then your off to v2, do not pass go, do not collect $200.
That is why you take extra care when releasing an API. It’s not like the rest of your devOps world with your fancy continuous integration pipelines. You don’t want to screw this up or potentially all of your users might suffer. So test, test, test before releasing your API.
In our case it wasn’t that bad. We soft-versioned because nothing really serious changed. We modified the datetime fields in our API, they were already ISO8601 compliant, the difference is before these were accurate to the millisecond. Apparently most people don’t like precision like that, who knew?
Apis.Guru is an interesting one, basically it’s a massive list of APIs that MUST have a specification document to be listed.
As of the date of this article there are two forerunners in the specification document game: Swagger and OpenAPI. They are not really competing types, more like versions. Swagger is a version 2.0 doc and OpenAPI is v3.0 at the moment.
Spec docs are incredibly useful, not only can humans read them in order to understand the intricacies of an API they may be interfacing with but more importantly computers can ingest/ consume them and spin up more precise machine-written code. Theoretically interfaces can be spun up on the fly although I don’t know if that’s being really done at the moment. Might be a future thing to watch for!
For the interested reader to get a taste of, the following are our spec docs:
As of February 9th, 2019 we are now listed on https://www.programmableweb.com/
ProgrammableWeb is more than just an API Directory service, it’s an informational resource for APIs: Stuff like whether they use XML or JSON, do they have spec docs? Versions, endpoint information, SOAP or REST and other ecosystem related queries one might have. They also have a very interesting blog for people who wish to watch the scene.
If you want to learn more about APIs, you should really check out David Berlind’s APIs 101 series on youtube.
We have launched our platform and are now ready to help you rapidly develop your product / subscription prototypes. Check it out!
Yes, this is our “Hello World” post, this is the KeyServ Platform v1.0 and we are proud to introduce this microservice API. Like most things that engineers design it starts with something built to make one’s own life easier. Such is the case here. SmartQ (Pty) Ltd has a number of SaaS and IoT projects and the one thing all these products have in common is the need for Serial-Key Tracking, it also enables us to offer our services with BYOL (Bring Your Own License) models in order to speed up the distribution of our offerings.
Our flagship product SmartQueuer (a live site can be seen here: http://q.communica.co.za) needed an agile subscription management system whereby we can allow users access to time-locked demos and trial periods to test in their environments at no cost.
Now all our subscription-based systems plug-into a centrally managed microservice. At this point lets talk about how awesome that is for SaaS and devOps. No more reusing the same subscription code snippets with poor maintainability across your portfolio, Microservice architecture saves us from that. Less code means less mistakes, more stability and more productivity time.
Learn about the API here : https://keyserv.solutions/Home/Learn
Start using KeyServ now: https://keyserv.solutions/Account/Login