none
Why is there no WSDL type support for Web Api? RRS feed

  • Question

  • So I am just getting started with .Net WebApi and one thing that I am noticing straight away is that there is no Contract defining how the Api looks and should be consumed (Request/Responses from each Action), this is usually in the form of a WSDL for WCF/Soap.

    It seems to me like this is something that would be very valuable and make life a lot easier for consumers of your Api.

    Is there a reason there isn't one? Is there a programming paradime or principle that I am unaware of? Is there a way I could create one?

    • Moved by Kristin Xie Wednesday, January 14, 2015 2:18 AM move to appropriate forum
    Tuesday, January 13, 2015 1:10 AM

Answers

  • Check this tool:

    http://blogs.msdn.com/b/webdev/archive/2012/11/08/enabling-asp-net-web-api-help-pages-for-asp-net-web-forms-applications.aspx


    Fouad Roumieh

    Tuesday, January 13, 2015 9:52 AM
  • SOAP, REST AND PEOPLE'S CREATIVITY

    SOAP needs a description document like WSDL because each resource can be consumed with different messages, there are no definition on the protocol about constraints to the possible names/messages that you can manipulate a resource.

    For example, in SOAP your web service that allow clients manipulate an user can expose the operation that create an user in many different messages, like:

    addUser
    createUser
    insertUser

    Of course, these are just few sample messages, because I've see a lot of funny web services method names. There are really creative people out there.

    In other hand, if you are exposing your underlying system using web api that really respect the REST principles, the client just need to know that you have a resource named Users, because there is 99% of chance that you can create an user in this way

    POST /Users

    And this occurs for each operation you want to expose using SOAP or a web api REST.

    Despite being SOAP a protocol, which restricts what you can or can not do, and be REST a style architecture, which leaves many open points of how to do things. There are efforts to define conventions of how to expose and consume REST web apis.


    DESCRIBING A WEB API REST

    In the field of how to describe a web api REST I can cite Swagger. It is not a attempt to create a WSDL like to web api REST, but it is a good attempt to create an open standard for describing web apis REST.

    Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.

    I use Swagger a lot and really love it, mainly because Swagger UI that allow you generate a nice live console and documentation for your web api.

    There are many implementations of Swagger for most of languages: C#, Java, Python, Ruby, etc.

    If you are using ASP .NET Web API, there a some projects to auto generate the Swagger specification, like Swagger.NET


    GENERATING CLIENTS TO A WEB API REST

    Because the constraints of REST, like the limited set of verbs (GET, POST, PUT, DELETE, etc) is not so difficuty to generate a client library to a web api REST.

    Projects like WebApiProxy can easily generate clients do C# and Javascript.


    CONVENTIONS FOR WEB API REST

    To keep our lifes as developers easier is good define some conventions of how our web api REST will behave, the best effort I know in this field is the very good Apigee - Web Api Design ebook. The e-book is not an attempt to create a bible or a mantra about how to design your api, but rather a collection of conventions observed in large web REST apis, like Twitter, Facebook, Linkedin, Google, etc.

    Tuesday, January 13, 2015 11:34 AM

All replies

  • Check this tool:

    http://blogs.msdn.com/b/webdev/archive/2012/11/08/enabling-asp-net-web-api-help-pages-for-asp-net-web-forms-applications.aspx


    Fouad Roumieh

    Tuesday, January 13, 2015 9:52 AM
  • SOAP, REST AND PEOPLE'S CREATIVITY

    SOAP needs a description document like WSDL because each resource can be consumed with different messages, there are no definition on the protocol about constraints to the possible names/messages that you can manipulate a resource.

    For example, in SOAP your web service that allow clients manipulate an user can expose the operation that create an user in many different messages, like:

    addUser
    createUser
    insertUser

    Of course, these are just few sample messages, because I've see a lot of funny web services method names. There are really creative people out there.

    In other hand, if you are exposing your underlying system using web api that really respect the REST principles, the client just need to know that you have a resource named Users, because there is 99% of chance that you can create an user in this way

    POST /Users

    And this occurs for each operation you want to expose using SOAP or a web api REST.

    Despite being SOAP a protocol, which restricts what you can or can not do, and be REST a style architecture, which leaves many open points of how to do things. There are efforts to define conventions of how to expose and consume REST web apis.


    DESCRIBING A WEB API REST

    In the field of how to describe a web api REST I can cite Swagger. It is not a attempt to create a WSDL like to web api REST, but it is a good attempt to create an open standard for describing web apis REST.

    Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.

    I use Swagger a lot and really love it, mainly because Swagger UI that allow you generate a nice live console and documentation for your web api.

    There are many implementations of Swagger for most of languages: C#, Java, Python, Ruby, etc.

    If you are using ASP .NET Web API, there a some projects to auto generate the Swagger specification, like Swagger.NET


    GENERATING CLIENTS TO A WEB API REST

    Because the constraints of REST, like the limited set of verbs (GET, POST, PUT, DELETE, etc) is not so difficuty to generate a client library to a web api REST.

    Projects like WebApiProxy can easily generate clients do C# and Javascript.


    CONVENTIONS FOR WEB API REST

    To keep our lifes as developers easier is good define some conventions of how our web api REST will behave, the best effort I know in this field is the very good Apigee - Web Api Design ebook. The e-book is not an attempt to create a bible or a mantra about how to design your api, but rather a collection of conventions observed in large web REST apis, like Twitter, Facebook, Linkedin, Google, etc.

    Tuesday, January 13, 2015 11:34 AM