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.