Why is there no WSDL type support for Web Api?

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 paradigm or principle that I am unaware of? Is there a way I could create one?

Answer 1

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.

Answer 2

In a nutshell, because SOAP was designed to be self-descriptive: A SOAP endpoint usually includes a wsdl that describes what operations it provides, and how the data looks (by means of embedded XSD's) that each operation takes and/or returns.
Because of this self-descriptiveness, it is possible for an application such as Visual Studio to generate a webservice proxy for it.

In addition, there are several extensions to SOAP (the WS-* specifications) that allow encryption or transactional behaviour to be used with SOAP. The idea is that you can use SOAP as your one-stop shop to create enterprise-grade webservices.

On the other hand...

WebAPI is designed to provide REST services. The communication format for REST is usually JSON or plain xml - although it really doesn't matter, it could even be plain text. REST services follow a completely different philosophy: they are meant to be lightweight so that they can easily be consumed by client-side scripts as part of an AJAX solution, or by mobile devices.
As such, there is a need to keep the level of ceremony to a minimum, including self-descriptiveness. Also, even if you wanted to, most communication formats used in REST services (such as JSON) don't have a formal way of describing their contents anyway.

Summarizing, you could say that SOAP webservices are usually used to integrate (possibly disparate) solutions, whereas REST services are better suited to provide communication between parts of the same solution.

Answer 3

SOAP/WS-* and RESTful APIs are not the same. If you want to build SOAP/WS-* WSDL supporting APIs the tool of choice in the Microsoft stack is WCF, mounted with an HTTP binding option (there are XML and JSON binding options, XML being the WSDL supporting option).

In practice, consuming a WSDL from a different implementation language or platform has been problematic. WS-* security layers over the top even more so.

My own experience has mostly been with .Net, Node, Java and PHP in this regard, and I can say that when you have platforms that don't have to define the details of a child type, or will use "Object" as the definition, it gets problematic to say the least. Beyond this, for the most part nobody really understands all of SOAP/WS-* relying heavily on tooling to make it work. This tooling has a lot of overhead, and different systems operate differently.

These are some of the reasons people looked to try simpler implementations. REST services (ala Web API) offer endpoints around objects/state. The idea being it's easier to define a set of simpler object structures represented in JSON format, and the endpoints to use against these structures than it is to try to use WSDL from an alien environment that doesn't work, then try to dig in and work around the problem.

Ironically, this is one of the areas I've used Node in a lot as a translation service, simply because it was flexible enough to accept dirty implementations as a client, and I could write simple clients against my adapted payload that worked better. EX: C# gets JSON text, that I use JSON.Net to convert to an object representation that I defined actually worked when I couldn't use a WSDL import.

In practice this happens a lot.

Answer 4

While a lot of the answers here are great, I think the answer is MUCH simpler: you're looking at the wrong technology for the job.

If you're looking to build a SOAP-service, you really should stick to WCF. It's still a very powerful framework, Microsoft is still actively developing it, no announcements were made for us to think it's going anywhere in the future, and it was made with this in mind. Web API does in no way supersede WCF (although it's probably trendier than WCF).

Web API used to be part of WCF, but it was moved over to the ASP.NET family exactly BECAUSE it didn't really fit alongside the other WCF technologies. Web API is much more concerned with using HTTP as an application protocol than a transfer protocol. In Web API, the HTTP verbs are king, in WCF HTTP merely serves to enable the SOAP protocol.

Don't blame Web API for not giving the ability to do certain things that it was not made for.