So in the fast pace world where daily a new invention is taking place, it is also challenging to keep up with the pace with the technology. There were days and when Web Services (created in .Net) were meant for being consumed by say a Client Web Application or desktop application. Now a days with more and more platform scaling up its important to have a service which can be used cross platform. Which I basically mean that a service once created can be consumed by Web Application, Android App, iOS App, Windows Mobile App, etc. In order to make this happen, I know you all are aware up till now that json is the apt to be used. So what’s new over here !!!

Well just creating service is not mere enough for having a good scalable Web API Service, one should have a good architecture in place which will make like easy to maintain our service in the long run.

Here are few must have components which are essentials for a Web API service.

  1. Authentication and Authorization (Security)- With security as a major concern its very essential to know who is accessing your service and what is he intended to be shown. This can be achieved using OAuth2.0, Identity Server etc. There many blogs out there, though important I would leave this topic open for discussion.
  2. Versioning of Web API – Many have the opinion that in REST service do not really require version, but here I’m discussing about versioning not to communicate implementation changes but to communicate incompatible interface changes.Like any good network or programming interface, you should strive for backward compatibility when you design a RESTful web service. However, you might need to break that backward compatibility some day, and if you have to do it, then you will be happy to have included a version number from day one.However, incrementing the version number to indicate a backwardly-compatible change (like adding a new API method) doesn’t help anyone, nor does incrementing the version number because of an internal implementation change.A great way to do this is to include the version number as a single-digit number in the URL path of your API, like this:

    http://api.myapp.com/V1/things

    You should only change the version number if you make an backwardly-incompatible change, like deleting or renaming a URL pattern. That means that the version number should change rarely if ever. If you end up going into double-digits, then you are probably doing something wrong.
    You have published your APIs and people have written programs based on those. If you update your APIs response with some major changes, which you have to do many times, these programs might break creating havoc for your developers. But if you create new API URL with ‘/v2’ keeping the old as ‘/v1’, your developers will vouch for your integrity.
    There are many popular APIs today like Twitter, Foursquare, LinkedIn, and the Yahoo Maps APIs have a version number in their URL, as do others I’m sure.

  3. Documentation – Well I know most of the developers hate creating documents 🙂 but in Web API service to be consumed by other developers in a cross platform environment it is important to have documentation in place. And well !! here documentation is not the word documents you developers are creating. So documentation of Web API can be exposed by using Swagger UI (http://swagger.io/), Web API Help Pages, etc.
  4. Consistency – This is really very important aspect. If the response from Web API service is always different for different methods or different in case of valid response or exception then the developers who are consuming your Web API will have a hard time handling such scenarios. So it is important to have a uniform response from Web API.
    For example you have a method which provide valid response as –
    {         “Id”:42,
              “QuestionText”:”This is a test question”,
              “QuestionImageUrl”: “http://www.blah.com/test.png”}
    While Invalid response will response as –
    {

              “Invalid question Id”

    }
    Thats where uniformity has to be brought in.
    Where whatever scenario is for valid or invalid response, the response obtained from the Web API will be as below,
    Valid Response
    {

                     “Version”:”1.2.3″,
                     “StatusCode”:200,
                     “Result”:
                     {
                                      “Id”:42,
                                      “QuestionText”:”This is a test question”,
                                      “QuestionImageUrl”: “http://www.blah.com/test.png”
                     },
                     “ErrorMessage”: null
                     }
    Invalid Response

    {

                     “Version”:”1.2.3″,
                     “StatusCode”:400,
                     “Result” : null
                     “ErrorMessage”:”Invalid question Id”

    }
    In another post I will explain how you can create such a response just by having and global delegate handler. (Till that time you can view the code at WebApiArchitecture/Infrastructure/ApiResponseHandler.cs)

  5. Server Side Validation – Whatever request that is obtained by your Web API Service, should be validated. This can be done using the Data Annotation for the Request object and checking for the Model State. This can also be handled globalling using the below mentioned custom Action Filter  WebApiArchitecture/Infrastructure/ValidateModelStateAttribute.cs
  6. Logging and exception handling – Just like any other software program this is must have essential in a Web API which make debugging and maintaining of the application less cumbersome.
  7.  ……….
  8. ……….

The list can go on and on .. but these are a few that will help in build a good Web API Architecture which can be used by cross platform applications. Most important in the boundary of cross platform I think would be the consistent response from Web API.

Here is the GitHub URL for the Sample Project that I have created which contains,

https://github.com/sagarwasule/WebApiArchitecture/tree/devlopment

  1. Global consistent response handler
  2. Logging
  3. Global Server Side Validation using Action Filter

I will improve this more to implement swagger ui for documentation, versioning, authentication and authorization, global unhandled exception handling, etc

Do lets discuss in comments in case you have some more points which you have an opinion as a must have essential component in Web API.

 

 

 

 

 

 

 

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s