Ideal REST API design

Introduction / short history

api2

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

Web API on IIS 8.0 – 405 Method Not Allowed for PUT

Lately I’m extensively developing my web services in ASP.Net Web API and generally speaking it’s good framework in supporting HTTP programming (REST “style”), even if it is in it’s early stages and needed more features to be “completed”.

Yesterday I had a very interesting problem when I published new version of my project (btw, I am developing web api in ASP.Net 4.5 and deploy it in Windows Server 2012 and IIS 8).

When I hit my web api with a PUT request (PUT -> api.mydomain.com/profilecontroller/) web server’s response was error 405 (or method not allowed) while in same time my controller supported all types of requests (get, post, put, delete).

I was surprised with this error while just few minutes earlier everything worked perfectly.

I googled for some time and get disappointed with results – no solution found.

Started to think what I did with my web server and I remembered some “not friendly” touches 😀 in Web Server (IIS) Role configuration, like installing “WebDAV Publishing”.

I immediately uninstalled (unchecked) that “feature (not Windows Feature :D)” in Web Server (IIS) Role and everything started to work like a charm :D.

IIS Role WebDav

It was kind of a stupid solution (I have to admit) but finally everything worked fine :D.