103

I have been reading about REST and SOAP, and understand why implementing REST can be beneficial over using a SOAP protocol. However, I still don't understand why there isn't the "WSDL" equivalent in the REST world. I have seen posts saying there is "no need" for the WSDL or that it would be redundant In the REST world, but I don't understand why. Isn't it always useful to programmatically bind to a definition and create proxy classes instead of manually coding? I don't mean to get into a philosophical debate, just looking for the reason there is no WSDL in REST, or why it is not needed. Thanks.

skaz
  • 21,962
  • 20
  • 69
  • 98
  • 4
    I have the same question. It seems from a clients perspective restful services are much harder to use then a WSDL service. – w.donahue Nov 06 '10 at 03:36
  • 4
    It seems to me that if you are exposing something simple, then you don't need a WADL or WSDL. But if you are exposing something as complex as SAP... I cannot fathom not having some kind of reflection and namespace to handle the plethora of functionality. – Brain2000 Aug 24 '11 at 23:45
  • Couldn't the HTTP OPTIONS method be considered an "equivalent" as it should provide information on the available methods and parameters needed for any possible action? – Dim13i Aug 08 '14 at 08:26

8 Answers8

51

The Web Application Description Language (WADL) is basically the equivalent to WSDL for RESTful services but there's been an ongoing controversy whether something like this is needed at all.

Joe Gregorio has written a nice article about that topic which is worth a read.

disooqi
  • 617
  • 10
  • 19
joschi
  • 12,746
  • 4
  • 44
  • 50
  • 1
    Thanks Joschi. I read the articles, but didn't find the second too convincing. Which points that he addresses did you find most valuable? – skaz Nov 06 '10 at 14:06
  • 1
    It might be worth noting that .NET also has a way to publish metadata (http://msdn.microsoft.com/en-us/library/ms730243.aspx). With that said, most REST services that I have seen developed by the big sites include a variety of downloadable clients developed for the major programming languages (Java, .NET, PHP, etc). In my opinion, this places a lot of burden on the service provider. – dana Nov 06 '10 at 16:42
  • 4
    @dana: Seems not much point in writing a service that then requires you to also write the client? – BlueChippy Oct 10 '12 at 07:11
18

WSDL describes service endpoints. REST clients should not be coupled to server endpoints (i.e. should not be aware of in URLs in advance). REST clients are coupled on the media-types that are transfered between the client and server.

It may make sense to auto generate classes on the client to wrap around the returned media-types. However, as soon as you start to create proxy classes around the service interactions you start to obscure the HTTP interactions and risk degenerating back towards a RPC model.

Darrel Miller
  • 139,164
  • 32
  • 194
  • 243
  • 4
    Can you elaborate a little bit more? I am afraid I don't get it. Thanks. – skaz Nov 06 '10 at 14:05
  • 2
    Proxy classes are a way to have machine validation at compile time. Without them, you only have manually written docs and testing-based "validation". – Eric Grange Sep 27 '12 at 03:47
  • 1
    @EricGrange ...and yet this approach has worked pretty well for the web so far. – Darrel Miller Sep 27 '12 at 13:08
  • 1
    @DarrelMiller depends what you call "worked well", this is like in the 80's when everyone would write its interops out of paper docs, so it works, but "well"? – Eric Grange Oct 03 '12 at 23:54
  • 2
    @DarrelMiller: Coming from a banking background, REST has no benefits. You NEED strong typing and compile time validation - otherwise you are simply writing test scripts against "something"...get the set of scripts even slightly wrong and you won't know until it's too late. – BlueChippy Oct 08 '12 at 11:45
  • 1
    @BlueChippy Despite what you see in common practice, REST is actually very strongly typed. Every payload has a media-type which has an associated specification that describes the semantics of the payload exactly. REST APIs should never require clients to understand semantics that are not explicitly referenced in the HTTP message. – Darrel Miller Oct 08 '12 at 14:10
  • 1
    Thanks @DarrelMiller - perhaps its just the implementations that are poor then. However, leads to the question HOW do you retrieve the media-type specification? I don't want to dislike REST...but everything I've worked with has left me feeling it's a quick-and-dirty solution...please prove me wrong. – BlueChippy Oct 09 '12 at 04:14
  • 4
    @BlueChippy Media-type specs are dealt with the old fashioned way. You either find an existing parser for the spec, or you go read the spec and write one yourself. The important thing to note is that the objective is for media type specs to be re-usable across APIs. Writing a new parser for each API defeats the point. REST when done right is for the very long term benefits of independent evolution of client and server. – Darrel Miller Oct 09 '12 at 12:20
  • Thanks again @DarrelMiller -1) What are "media-type specs" - the one I've been given is a word document, which has inconsistencies in it that I can spot even before development! -2) Does that mean Media-Types are intended to be "global" and unchanging? e.g. If the RESTful service I GET from changes it's media-type then how do I know until I get an error? What if the media-type itself changes/evolves? Are you supposed to version the media-types? – BlueChippy Oct 10 '12 at 07:13
  • @BlueChippy The globally registered media types are here http://www.iana.org/assignments/media-types/application/index.html You can create your own, you should register them, The HTTP header Content-Type tells you which media type the server is returning. You can tell the server which media-types you understand in the request Accept header. You can version media types but it is better to design them to evolve. A HTML 1.0 doc can still be consumed by today's web browsers and still has text/html as the media type. – Darrel Miller Oct 10 '12 at 12:25
  • @DarrelMiller Q) Are RESTful services more geared towards interacting with something visual? i.e. a website/newsfeed? e.g. You can build your site around someone else's restful services to interact with it...therefore, as long as you know the first bit to get started, any remaining interaction (URI) is returned by the service itself? – BlueChippy Oct 15 '12 at 04:48
8

RSDL aims to turn rest like a hypermedia, in other words, it has more information than a service descriptor like WSDL or WADL. For example, it has the information about navigation, like hypertext and hyperlinks.

For example, given a current resource, you have a set os links to another resources related.

However, i didn't find Rest Clients that supports this format or Rest Server Solutions with a feature to auto generate it.

I think there is a long way for a conclusion about it. See the HTML long story and W3C vs Browsers lol.

For more details about Rest like Hypermedia look it: http://en.wikipedia.org/wiki/HATEOAS

Note : Roy Fielding has been criticizing these tendencies in Rest Apis without the hypermidia approach: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

My Conclusion : Now a Days, WADL is more common that Rest and Integration Frameworks like Camel CXF already supports WADL ( generate and consume ), because it is similar to WSDL, therefore most easy to understand in this migration process ( SOAP to REST ).

Let's see the next chapters ;)

Eduardo Fabricio
  • 2,151
  • 2
  • 25
  • 32
8

Isn't it always useful to programmatically bind to a definition and create proxy classes instead of manually coding?

Agree wholeheartedly, this is why I use Swagger.io

Swagger is a powerful open source framework backed by a large ecosystem of tools that helps you design, build, document, and consume your RESTful APIs.

So basically I use Swagger to describe my models, endpoints, etc, and then I use other tools like swagger-codegen to generate the proxy classes instead of manually coding it.

See also: RAML

Alex Nolasco
  • 18,750
  • 9
  • 86
  • 81
6

There is an RSDL (restful service description language) which is equivalent to WSDL. The URL below describes its practice http://en.wikipedia.org/wiki/HATEOAS and http://en.wikipedia.org/wiki/RSDL. The problem is that we have lots of tool to generate code from wsdl to java, or reverse. But I didn't find any tool to generate code from RSDL.

richard
  • 1,845
  • 1
  • 20
  • 30
3

WSDL is extensible to allow description of endpoints and their messages regardless of what message formats or network protocols are used to communicate

However, REST uses the network protocol by using HTTP verbs and the URI to represent an objects state.

WSDLs tell you at this place, if you send this message, you'll perform this action and get this format back as a result.

In REST, if I wanted to create a new profile I would use the verb POST with a JSON body or http server variables describing my profile to the URL /profile

POST should return a server-side generated ID, using the status code 201 CREATED and the header Location: *new_profile_id* (for example 12345)

I can then perform updates changing the state of /profile/12345 using the HTTP verb POST, say to change my email addresss or phone number. Obviously changing the state of the remote object.

GET would return the current status of the /profile/12345

PUT is usually used for client-side generated ID

DELETE, obvious

HEAD, gets the status without returning the body.

With REST it should be self-documenting through a well designed API and thus easier to use.

This is a great article on REST. It really help me understand it too.

roder
  • 566
  • 6
  • 13
  • 2
    I would argue that it is the hypermedia constraint of REST, more so than the uniform interface constraint that removes the need for WSDL. – Darrel Miller Nov 06 '10 at 13:56
  • 3
    Where to you discover "profile"? How do you provide assistance when instead of one, you have dozens? All the rest service out there rely on hand-written docs and manually written APIs, which are labor intensive and error-prone. – Eric Grange Sep 27 '12 at 03:45
  • 2
    I agree with @EricGrange - please could you explain HOW you know what entities you can perform CRUD(L) operations ON...unless someone writes it down somewhere? – BlueChippy Oct 08 '12 at 11:47
2

WSDL 2.0 specification has added support for REST web services too. Best of both worlds scenario. Problem is WSDL 2.0 is not widely supported by most tools out there yet. WSDL 2.0 is W3C recommended, WSDL1.1 is not W3C recommended but widely supported by tools and developers. Ref: http://www.ibm.com/developerworks/library/ws-restwsdl/

supernova
  • 3,111
  • 4
  • 33
  • 30
0

The Web Application Description Language (WADL) is an XML vocabulary used to describe RESTful web services.

As with WSDL, a generic client can load a WADL file and be immediately equipped to access the full functionality of the corresponding web service.

Since RESTful services have simpler interfaces, WADL is not nearly as necessary to these services as WSDL is to RPC-style SOAP services.

JSS
  • 2,061
  • 1
  • 20
  • 26