REST in the Practice

July 22, 2018
http rest api

IMO: REST in Practive versus REST in Theory

One of the best/s parts of developing is the juxtaposition of theory and practice. I am sure there are many other channels where these two point of views collide judt as frequently. However, since software engineering/programming/developing doesn't have a true body of overseers, certifiers or anything similar it's, at times, the wild, wild west.

For instance, a given task can be performed one of 10 ways and whilst there may be a best practice (under certain [but certainly not all] circumstances) how you decide to do it just depends.

REST is one of those things. So many right ways to do it. As a well written example of the turmoil that surrounds REST APIs, read Troy Hunt's post on API versioning - he decided to version his API three different ways just to satisfy all the expected ways that versioning could be performed.

The issue that prompted this post: ASP.NET Core 2.1 has decided that automatic model validation is Awesome and that a 400 (bad request) will be returned immediately. Thank you, Microsoft!!!

No. Not really.

I get it, but no. If my request was successful I want a 200. I want all the http libraries I use to tell me, YES, YOU MADE IT!! The response (the response code) should tell me my status. Because a 400 bad request does not tell me anything, except BAD. What was bad? Why did you fail? Partial success? And that's the issue. All the variations of "bad" mean that I will now have to deal with all the different scenarios. As a consumer, that's a pain. I much prefer a response that says, you got to your destination, but something went wrong and this is what that is.

What do I do? I return 200 - you got to your destination endpoint and it didn't blow up. Great, step 1: check. Next, check the response. I usually return something like: { status: int, ok: boolean, errors: string[], hasErrors: boolean, entity: object }. As long as I get a good response back, I can check:

if(response.Ok){}

or

if(response.status === 1){ /* 1 = ok, 0 = bad */}

if(response.status === 3){ /* special app aware status code that needs to be dealt with */}

While I understand the concept of REST and HTTP codes and why this was done, I am not sure that in practice it makes a lot of sense. Most of the APIs I have consumed and worked with usually will respond with 200 and an object that you can parse to determine the fate of your request. I understand that I could just say if it is 200 then it's 100% good and if it's 400 then I need to check for why it was bad. Why is this a lot more work for me? Because libraries like AngularJS will automatically infer a non-200 response as BAD and send it to an exception handler or such which gets in the way of normal app processing.

That's my gripe. Luckily, I can just configure it to be what I want (even though it's an extra step with every new project). Great post and more info here:

https://www.strathweb.com/2018/02/exploring-the-apicontrollerattribute-and-its-features-for-asp-net-core-mvc-2-1/