RESTful World Starting to Make Sense

As many of you, I’ve come from a classic SOAP world and not having the standardisation in the restful world gives me shivers. But that’s not the case anymore, it’s all hanging together rather nicely now.

When you start to work on the RESTful design of your APIs, the following questions arise very quickly-

  1. How do I describe my API to the external parties without having to maintain the documentation all the time which can go out of sync very quickly?
  2. How do I share the contracts only with the other development teams, allowing them to work independently in a decoupled manner.
  3. How do I validate the request-response from/to the client?
  4. How do I create test harness with load tests automatically?

So here are the answers which will hopefully give you some comfort-

Describe your API-

Swagger is the WSDL of RESTful world. Swagger has been recently adopted by Open API Inititaive (OAI) for its OpenAPI Specification making it a vendor nuetral industry standard. OAI is backed by the key industry players like APIGEE, IBM, Google and of course Microsoft. Notably, AWS is not the member yet but it’s API Gateway is compatible with Swagger.

Type System-

Json Schema is the Xsd of the RESTful world. OAI specification (fka swagger) uses standard type system/schemas language defined by Json Schema Draft 4, atm. Json schemas are backed by IETF, again making it vendor nuetral industry standard.


Json schema website provides a bunch of links to the popular/useful tools here. If you are a .net shop then Newtonsoft Json Schema SDK is your best option, you can’t go wrong with it.

In Azure world, Swagger is fully supported as well. As an example- API Management, API Apps and Logic Apps, they all support Swagger (now known as OpenAPI Specification).

Equally, ARM Template Schemas use Json Schema Draft 4 specification to describe the resource templates, making it open and vendor nuetral to integrate with any external tooling. This is a great example as well if you wanted to see production grade schema and it’s design e.g. types, constraints etc.

That’s said, it is inevitable to avoid any further improvements/refinements in this space but I am confident, the direction of travel will not change much anymore, so it’s safe to use the above (in my opinion) for your RESTful design and evolve together as an industry.

Can’t Create VM/Resources in Resource Group

My customer recently ran into this problem, which will come up when you try to configure your environment properly i.e. create a resource group and give only the required access to the resources in your organisation, following the principle of least privilege. The structure looks like below-


What’s going on here?

Objective: Anthony is a subscription admin and he wants to ensure a role based access control in applied to the resource groups. He takes the following steps to achieve this-

  1. He creates a resource group called A and give a ‘contributor’ access to the user called ‘Ben’.
  2. He then informs Ben to go ahead start using the resource group for the project.
  3. Ben logs into the portal with his credentials and try to create the resource.
  4. Resource creation fails with the error which looks like below- Registering the resource providers has failed. Additional details from the underlying API that might be helpful: ‘AuthorizationFailed’ – The client’ with object id ‘b8fe1401-2d54-4fa2-b2dd-26c0b8eb69f9’ does not have authorization to perform action ‘Microsoft.Compute/register/action’ over scope ‘/subscriptions/dw78b73d-ca8e-34b9-89f4-6f716ecf833e’. (Code: AuthorizationFailed)

This will stump most of the people as expected. Why? because if you have the contributor access to a resource group, surely, you can create a resource e.g. a virtual machine. What went wrong here- Carefully at the error message and focus on ‘Microsoft.Compute/register/action’ over scope ‘/subscriptions/dw78b73d-ca8e-34b9-89f4-6f716ecf833e’. What does this say? it’s not the authorisation error to create a resource, it is the authorisation error to register a resource provider. This is expected, we don’t want a resource group level identity to register/unregister the resource providers at the subscription level. So how do we solve it? Option 1

  1. Log into Azure with an identity which has a subscription level access to register a resource provider e.g. admin/owner.
  2. Using PowerShell (PoSh) register the resource providers you need at the subscription level. You can also see which providers are available and registered already. Sample script is given below-

$subscriptionId= "<Subscription Id>"
Select-AzureRmSubscription -SubscriptionId $subscriptionId

#List all available providers and register them
Get-AzureRmResourceProvider -ListAvailable | Register-AzureRmResourceProvider

Options 2

  1. Let the subscription admin/owner create the resource e.g. a VM.
  2. This will implicitly register the resource provider for the resources created.

Hope this was helpful.

I’ll be talking to the engineering to see if we can improve this user experience.