Web API Architecture RRS feed

  • Question

  • Hi,

    I want to create web Api to perform my database operations.I would like to know best approach to create web Api methods out of below two approaches:

    Giving example for SignIn operations

    1) APIResponse Method1(APIRequest)

    APIRequest contains below property:


    KeyValue of DIctioanary is initialized as below from UI COntroller

    (i) Key-EmailAddress, Value-"EmailAddress"

    (ii) Key-Password, Value- "Password"

    Advantage of this method is even if we require any other parameter in webApi, we can simply add key value pair from UI Controller and send dictionary to WebApi without any changes in WebApi

    2) SignInResponse Method1(SignInRequest)

    SignInRequest contains below property:

    (i) EmailAddress,

    (ii) Password

    In this approach, if we need any extra parametr in request, we need to change request Contract

    So what approach is the best to use. Can anyone help me in this?

    Thanks in Advance


    Monday, June 15, 2015 5:28 PM

All replies

  • Change the question. If you write any class, would you write Method(Dictionary) or Method(arg,arg2...argN) and why?


    Thursday, June 18, 2015 12:43 PM
  • My pedantic tenancies aside (e.g. method names, sending password through a Web API, etc.), of the two approaches you've laid out above, I would recommend the second approach for a couple of reasons:

    1. While a generic Dictionary data structure makes complete sense in the .NET world, if your API ends up being used by non-.NET clients (think mobile) then it might cause some confusion. Not a particularly huge issue since it all boils down to JSON (or XML) but the API docs could be confusing.
    2. Speaking of API docs, if you want to make use of an API documentation technology, such as Swagger/Swashbuckle), then the 2nd approach will be easier/make more sense to document. For example, as a consumer of your API, I'd much rather read an API doc that tells me I need to pass in an e-mail address and a (hashed!) password vs. a generic dictionary - where the docs might not tell me what key/value pairs for the dictionary. A dictionary also lends to run-time errors since misspelled key names won't be detected at compile time.

    All that said, if you expect your API to change A LOT then the first option (or a variation of it) might make more sense.

    Hope this helps!

    --- Thanks, Jeff (http://devmatter.blogspot.com/)

    Friday, July 17, 2015 12:09 PM
  • As others have pointed out try to define your interface boundaries as much as possible. This makes it easier to test, makes the intentions of your code clearer to callers, and makes it easier to document.

    If you already know there is a method (or more) that could be extended in the future then you could wrap up those arguments in a containing class and extend the class with optional parameters when the time comes. This should not break existing implementations of your interface.


    // Version 1
    public interface ISecurityService {
       bool LogUserIn(LoginRequest loginRequest);
    public sealed class LoginRequest {
       public string EmailAddress {get;set;}
       public string Password {get;set;}

    Now lets say you want the option to remember me as well. All you have to do is extend the LoginRequest with an optional parameter, the interface ISecurityService does not need to be touched.

    public sealed class LoginRequest { public string EmailAddress {get;set;} public string Password {get;set;}

    // added in Version 2 public bool? RememberMe {get;set;} }

    Mark as answer or vote as helpful if you find it useful | Igor

    Friday, July 17, 2015 2:31 PM