Restful WebServices / API's - proper use of HTTP Verbs and HTTP Status Codes

While writing code to consume Restful Web API's, as well as seeing some of the Restful Web API's written in some of the companies I've worked with, I get frustrated at times. I see a lot of implementations where  basic, simple principles of a Restful Service are not followed. The 2 common issues that i see a lot are

• Incorrect HTTP Verb is used. HTTP Post is used all the time. Even when it is to Get or Delete a resource, a method/url called GetCustomer or DeleteCustomer will be written and it expects a request Posted to it.
• Incorrect HTTP Status Codes are returned. Sometimes Status Code 200 is returned all the time with the error message in the response body. 

I thought I'd write a quick blog as a reference to how the Restful Web Services should be implemented, the verbs which should be used, and the different HTTP Status Codes returned for different scenarios.

Let's assume i have a Restful Web Api, called http://mywebapi.com/Api. It can be used to create/update/get/delete Customers.

Get a Customer

URL:  http://mywebapi.com/api/customer/{customerId}
Http Verb: Get

• If a customer with the provided id is not found, return HTTP Status Code of 404 (Not Found)
• If a customer is found, return customer with HTTP Status Code of 200 (OK).

Get a List of Customer

URL:  http://mywebapi.com/api/customer
Http Verb: Get

• Return the list of Customer with HTTP Status Code of 200 (OK). (If no customer was found, the list will just be empty.)

Create a Customer:

URL:  http://mywebapi.com/api/customer

Http Verb: Post

HTTP Request Body: The Customer object in Json format.

• If the Customer object can not be read/parsed from the HTTP Request Body, return HTTP Status code of 400 (Bad Request). 
• If the Customer object can not be created/saved in the DB, Http Status Code of 500 (Internal Server Error)
• If the Customer object is created, return HTTP Status Code of 201 (Created) + ideally the url of the new customer, for e.g. http://mywebapi.com/api/customer/104

Update a Customer:

URL:  http://mywebapi.com/api/customer/{customerId}

Http Verb: Put 

HTTP Request Body: The Customer object in Json format.

• If the Customer object can not be read/parsed from the HTTP Request Body, return HTTP Status code of 400 (Bad Request). 
• If a customer with the provided id is not found, return HTTP Status Code of 404 (Not Found)
• If the Customer object can not be updated/saved in the DB, Http Status Code of 500 (Internal Server Error)
• If the Customer object is created, return HTTP Status Code of 204 (No Content) 

Delete a Customer

URL:  http://mywebapi.com/api/customer/{customerId}

Http Verb: Delete

• If a customer with the provided id is not found, return HTTP Status Code of 404 (Not Found)
• If the Customer object can not be updated/saved in the DB, Http Status Code of 500 (Internal Server Error)
• Return HTTP Status Code of 200 (OK) + ideally the Customer Object which was deleted. 

Note:

SOAP, which used to be the primary standard for Message and Data exchange on the web, has been steadily replaced by Restful Services in the last few years, largely owing to it's simple design. 

In the .Net world, ASMX and WCF were used for creating SOAP Web Services and nowadays, ASP.Net MVC Web API is used for creating Restful Web Services. 

Angular 2 - Initial Impression

After working mainly with ASP.Net MVC for Web UI and some other JavaScript libraries, i finally got around to taking a look at Angular 2.

In this post i'll post my initial impressions and will dig deeper into Angular 2 in future posts.

First thing that got my attention is the Typescript Language, which is the language of choice for Angular 2. Typescript is a language developed by Microsoft and is a sort of an abstraction over JavaScript. Any code that is written in TypeScript eventually gets compiled/transpiled into JavaScript.  TypeScript felt closer to and Object Oriented Language like C# or Java, rather than the messy JavaScript. It has concepts like Classes, Constructors, Interfaces, Properties, Methods, Events, Strongly typed data types. As my main programming language has been C#, I found Typescript to be a pretty cool language which makes writing client side code a breeze. However, ppl who may have a a JavaScript background might have a different opinion about TypeScript..


Another thing that stood out was the discarding of the MVC / MVVM architecture which has been the trend in UI in the last few years (ASP.Net MVC, AngularJS, etc.) and using a component based architecture. Basically, the UI is broken down into smaller pieces and these pieces need to be implemented as a Component. A Component is  a TypeScript Class (with a Component Directive) and it would have it's UI html fragment in a separate Template file. The properties, methods, events and any logic would be in the TypeScript Class and the Template would bind to data in these as well as call it's methods and events. For those of you who have experience working with ASP.Net Web Forms, it might feel eerily similar to User Controls, with the UI Template file feeling like the UI *.ascx and the Component *.ts file feeling like the Code-Behind *.ascx.cs.

These Components could then be nested under other Components or put in directly under the Root Component, which would be loaded/bootstrapped into an .html page.

An application could have additional Service class, which could perform tasks like getting data from a Web Service. Components could have instantiate a Service Class and use it's methods to get Data or alternatively, the Services could be declared at the Root Component layer and then injected into the Component via the Constructor.


My initial impression of Angular 2 has, surprisingly, been very positive and am looking forward to doing a bit of deep diving into it.