Confessions after Two Years of Development on Azure REST API

First things first, I am no more attached to IFS. I got a new job offer in Kuala Lumpur from a small startup – who is a Microsoft Solution Provider Partner and works very very closely with Petronas ICT, Axiata, UEM, T-Systems, etc.

It has been almost two years since I moved from SDK based development on Azure to the REST API based development. It all stated after a discussion with a friend, who was going to be my future team mate while having lunch. He was explaining about the product they were working on and was asking me, how certain tasks can be done on Azure such as creation of some Azure resources programatically, and my answer was “Azure SDKs”, later he came back and said, the resources that were supposed to be created do not have an SDK, so they were chosen Azure REST APIs, and complained about the poor documentation. This was my starting point to Azure REST API, and have been a developer who liked APIs since my Windows Phone development days, I accepted the challenge. Before the ARM days, we had XML based API – fortunately, its no more (I mean, you don’t have any dependency on it)

giphy

Even today, I wrote some code to call an API, as the project / product I am working on now is more complex than the product I worked for at IFS. I just thought to share the pros and cons of moving to Azure REST API and this can be taken as a feedback to the team that makes the API possible.

Pros

  • Almost everything is possible – If you invest your money and time, you can simply create a portal / app / application, which is better than the boring, confusing and slow Azure Portal (it is improving, but Azure Portal is far better than AWS or Google Cloud portal to be honest) in terms of
    • Resource management
    • Billing
    • Monitoring
    • Etc…
  • API availability – Usually its really important for any APIs to keep the 99% SLA. But I just assume Azure REST API keeps 99.99999999% SLA. I could not find any documents or statements to relate my claim but I kept running an Azure Function to call the APIs and a single call did not fail. This Function is running since later August 2018 – perfactly.
  • Documentation and support for API playground – Since last year the documentation for Azure REST API has been improved and is simply superb, carries the right information, which is really needed.
  • Easy to learn – Its not easier like SDK, but comparing to the REST APIs of Google Cloud or AWS, this is straight forward, specially when it comes to authentication and handling multi-tenancy.
  • Response messages and human understanding exceptions – The response messages are just straight to the point as the exception messages. I simply love the fact this throws exceptions, when you call an API with wrong API version, the response body carries, what are the API versions supported for the specific resource – so if you are brave enough, you can parse that message and call the API again with correct API version. The same story is there for some other API endpoints too.
  • Fully REST – Even though this is not really a pro, after ARM, Microsoft has totally migrated their API from XML based SOAP. Even though the SOAP API does exist today, you can do everything using the REST.
  • HEAD Support – Even though its not documented, you can send a HEAD request to a GET endpoint for a quick check.
  • Keeping SOAP – Some legacy systems do support SOAP. So Microsoft still keeps this functionality. It does only matter if your “legacy” system needs some integration with Azure.

Cons

  • No uniformity in the values some response objects – this has been a headache for me. Eg: in the response of the Consumption Usage API – some of the resource IDs are getting prefixed with “/” and some are not. So if you want to manipulate the string – you might do some pre-processing first.
  • No uniformity in the response codes for similar operations. For example, the  unassigning a blueprint API (which is a DELETE call to the blueprint assignment ID) gives 202 until it gives a 204. But removal of a resource group does not give 204 (only 200 and 202)).
  • No unique URL parameter values for similar stuff (this will hit you very rarely) – In the case of Metrics API, some resources support different value for the same type of metrics. Eg: If you want to get CPU percentage for DB and a VM – you have to use “cpu_percent” if it is a DB and “Percentage CPU” if it is a VM – but end of the day, you need to get some thing that is identical.

So, these are the pros and cons and I think, to avoid some “whaaaaaaaat!!!” moments, you must play around with the API in the API playground, which is build as a part of the documentation. Azure REST API is simply great and better than the AWS or Google Cloud – yet need some improvements.

Happy Coding.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s