Ideal REST API design

Introduction / short history


In mobile (tablet is included) era REST eclipsed SOAP in terms of web services. And, if we see and analyse in details both architectures (respectively architecture styles), and get environment constraints get just data what I request instead of “two hundred pages manual what I will get” is great, practical and useful. Imagine a mobile user using mobile data to get ten most popular books and consuming a SOAP service, just getting WSDL will push that month’s data invoice to limits. But coming from SOAP, with a commodity and many things defined for years, REST APIs have open a lot of debates in almost all aspects REST tends to resolve, make solution. So, after all years in designing (and consuming a lot) REST APIs I did a list of things I consider an ideal rest api design should contain.

Media types

Every Web API must support several media types but two are considered un-avoided, XML and JSON. Because of a latest momentum of HTTP programming and following standards JSON tends to be the most preferred and for this reason should unequivocally  be default media type.

But XML has its own place, because of its robustness to present very complex scenarios and history (SOAP), if we can consider like this.

Partial results

If your API will be popular and you’re exposing big objects you will face situations in a big number of scenarios where there’s no need to get all fields of a resource, and if your api will support partial results will be a good benefit for consumers. Let’s take an example of countries resources, you will have an id, name, description, date added, status, shortcode, flag, etc. Most frequent scenarios when applications needs to display the resource are just Id (for internal relations with other information), name and possible flag, all other info you have / need for youself. But this, of course will come with a price in you infrastracture because querying will take longer and needs more resources (hope you will do something with caching). Continue reading Ideal REST API design

SOA applications tech stack

There are a lot of times when I am asked to complete a stack of technologies for building a Service Oriented Applications. And of course, like for everything, also for this topic there are a lot of answers (and opinions). Using this post I want to express my opinion based in my experience (through years in building medium-to-large applications for public and private sector), what are pieces to combine a SOA lego. So, here I am going to explain what are technologies that could be used to build a SOA application, of course Windows environment friendly. But, this post, is not attempting to give a complete tech stack for this type of apps.


Continue reading SOA applications tech stack