Building REST services, rambling …

With the recent changes in the web development like SPA and change in device platforms, the backend changed drastically.  Backend no longer just serving up pages, they are now moved to highly scalable, available and responsive service providers. Over the past year or so, I was purely focused on the front end development. I did not touch much of the backend since we had very talented people in the back end. But over the last couple of months, some of the changes happened in the backend made me look at the backend architecture. Similar to building highly testable and manageable front end, back end also should be able to sustain changes with out breaking the front end. That means, when you build services, you need to build them in such a way, they are self serving and highly discoverable services which can adopt to changes without breaking the clients.

Our back end is build with Web API. It is easy to put together simple hello world or student REST services. But when building enterprise web services, you need to put some time there to come up with what are the resources are you going to expose and how are you going to expose. For those who have been developing services using SOAP protocol, this is paradigm shift. So if you are going to build REST services, don’t just convert the SOAP to REST rather think about what are you trying expose.

I remember reading somewhere, building REST URL, resources and query parameters is 80% art and 20% science. I totally agree to that. When I sat in discussions initially, I was thinking it was pure waste of time. It is not a rocket science, but later I found out, building rest service end point is thing of beauty. Take time and look at the resources you are going to expose and why? Ask the question, are they really the resources clients want? Just because we have a resource in a table doesn’t mean we need to expose them as a resource. When you are exposing the resource, it should be meaningful to the end user and easy to use.

I am not going to explain how to build REST services. Vinay Shani wrote one of the best blogs on the REST services. Here are some of the major things I went through when I was consuming REST services and moved to building services.

  • Cache: Build your rest services in such a way, it leverages the caches. Poorly designed resources end up not using caches. Especially when you are building highly responsive services, cache is an important piece of the puzzle.
  • Versioning: There are three different ways one could version the services. I personally do not like versioning in the URL but on the other hand, we do not have mature technology to enable discovery either. I remember reading somewhere, if you start out with versioning, you are already admitting your failure. I loved this blog on versioning. Anyway you do it, you are doing versioning wrong 🙂
  • Query string/Resource hierarchy: Take care on how you want to set this up. This goes hand in hand with Cache. I prefer resource hierarchy than query string. I prefer to use query string only in how I want to the representation to be and filtering my results.
  • Documentation/Discovery: You could create an awesome service, like Taj Mahal and put in the middle of a forest where no one can find it, then there is no use. Also if you build mind blowing machine and if it is not easy to use what is the point. Build great API documentation, use tools like swagger or some other forms. Provide great on boarding story and excellent means for users to report problems and concerns like Forums/Discussion groups.

There are ton of resources available on the web. Before you start wiping up REST services, change you mind set, read what people went through ask questions and be smart in building resources. Like Troy said in his blog, once people start consuming, they are very important part of the equations so changes have to be handled very carefully.  We should not create distrubtive services that clients do not want to use. Only way you services be successful is if you clients consuming it and happy using it.