Is it mandated by any standard that a web service should provide a WSDL by appending ?wsdl to the endpoint address?
Is it OK if the WSDL is hosted at a different URL (without appending ?wsdl)?
For example:
Endpoint: http://abc.xyz.com/MyService
WSDL: http://abc.xyz.com/MyServiceDefinition.pqr
Note that I'm even using a different extension for the WSDL definition.
Does using this approach violate any standards or one can host the thing the way they want?
Is it mandatory to have a WSDL definition accessible using ?wsdl?
No, it's not.
A WSDL is used to describe a web service contract and is provided because it allows tools to automate generation of client stub code for calling the specified web service. Exposing the WSDL at the same location as the web service with ?wsdl appended to it is just very handy and that's the convention everybody uses.
People and tools look for the WSDL at that location and frameworks automatically expose it at that location but it's just a convention. As to my knowledge this isn't specified in any specification (or at least none that I could find).
Sometimes though you don't want to provide a WSDL that everybody can look at and try to create a client because it's a private web service and you only want to give access to your partners, not to everybody. At that point you can disallow the ?wsdl URL and provide the WSDL only to your partners by using an alternative channel. You can even e-mail it if you don't want it exposed online.
So you can choose whatever channel to expose it. Just remember that because people and tools are following this convention they are used to see it there and some (poorly written) tools might choke in a different extension, for example.
P.S. One other thing I wanted to mention - which isn't strictly related to this answer but kinda reinforces the convention - is the new ?singleWsdl option in WCF 4.5.
WCF, as most other tools, exposes the WSDL at the ?wsdl address but uses xsd:import statements with external schemas. Some frameworks were not able to process WSDL with imported dependencies so people started to write customizations over WCF to have a flat WSDL exposed, so much so that in the latest version of WCF Microsoft decided to add this feature out of the box.
But for backward compatibility they needed to keep the ?wsdl endpoint as it was (returning a WSDL document with xsd:import statements inside) and were forced to add a new query parameter for the flat WSDL: ?singleWsdl. I'm sure this idea will be picked up by other web service vendors and providers as well.
No, Its not mandatory to have ?wsdl access, but its recommended way.
Its worth noting that most clients will try to append "?wsdl" to your URL and will try to access WSDL file, Hence its highly recommended to setup it.
Related
I am going to deploy a SOAP web service on a WebLogic server.
The endpoint of the service is something like:
http://myserver.mycompany.com:1234/MyService-0.0.1-SNAPSHOT/MyServiceService
However, if (using a browser), I navigate to either
http://myserver.mycompany.com:1234/MyService-0.0.1-SNAPSHOT/MyServiceService?WSDL
-- or --
http://myserver.mycompany.com:1234/MyService-0.0.1-SNAPSHOT/MyServiceService?xsd=1
I can see the WSDL or schema file, respectively, for the service.
My group does not deploy a lot of web services (we're a back-office group and use Oracle Middleware to automate what little services we do provide), so a question has come up regarding whether exposing the WSDL file and schema file is "best practice".
Is it OK for these files to be visible, or should access to them be shutdown somehow? Conversely, is it even possible to restrict access to them, or would that interfere with clients trying to access the service?
This is an old question, but anyway.
It depends, but in my projects it was considered a bad practice to do so. You should always do Contract first, don't base your WSDL on your code or most likely you will end up with a WSDL that is somehow dependent on the programming language used for the implementation.
I don't know how Weblogic behaves but I remember that Jboss (5) used to generate the WSDL from the code any way and serve that. Even when we did Contract (WSDL) first development. So you would end up with little differences in these WSDLs which may cause problems. Exchange of the WSDL and the XML Schema files should be done by other means. It is possible to restrict access to any URI on Weblogic.
Another aspect is, that if you don't remove these, we found the developers on the clientside will start pointing their development-tools and implementation to these endpoints to get the WSDLs. This will most likely also cause problems and at least (a lot) unnecessary downloads of these files. As most frameworks will (need to) read the WSDL every time they instantiate the client-code. By not providing these endpoints, you keep the clients from these bad practices.
I had an endless argument with a friend recently. Our company exposes web services endpoints without their WSDL. WSDLs are hidden inside the system.
Some colleague say "it's better for the security". I say WHAAAAT ?
Another argument is "You don't need to expose the WSDL, because it is only used at development time".
So basically they say that when someone consume our web service, there is always a time where you pass the WSDL by email, in order to let them build a client. Once you are in prod, the WSDL is no longer used.
So, please, tell me I'm right. Tell me that when you expose a service to the outside world, you MUST expose the contract with the endpoint. It's THE RULE. talking about development is irrelevant here, right ?
My friend says that I'm biased because I wrote a dynamic gateway, so I need the WSDL at runtime, and this kind of scenario is very rare.
What really pisses me off in all of this is that the WSDL is considered as the .lib and .h of a .DLL or .SO, it's "just a thing required at development time".
I don't know what it is for CORBA and IDL... Does the IDL was exposed to the public at runtime ?
So, what is the right thing here ? I'm lost. The client is intended to receive the WSDL at runtime right ? Or not ? It should perform some kind of validation at runtime right ?
You are wrong. Making a good interface can take a lot of effort, years of experience, and the WSDL is a very detailed description of the service. If that is a secret, so be it. As authentication might be included, there is also a potential security issue.
I would like to argue that you should NEVER download the WSDL from a service if you can get the original instead. The online WSDLs are sometimes generated by the SOAP framework and things documentation will often not be included. Furthermore the endpoint address should always be explicitly set, never use the value which might be included in the WSDL.
In fact the right way to communicate the service definiton is not only a well-defined set of WSDL / XSDs but also with concrete request/response examples in including error responses.
Relying on downloading a WSDL to bootstrap your service is a receipt for disaster (if this stops your app from starting).
My messaging provider gives me two different kinds of WSDLs to use.
http://my.amazonaws.com:8000/webservice/?wsdl
http://my.amazonaws.com:8000/webservice/?singleWsdl
The first one is an embedded WSDL. Can NOT use it to generate WSDL2java packages and
can NOT use JAX-WS to create a connection.
The second one is a single WSDL. It can generate Java packages with CXF 3.0's WSDL2java and can use JAX-WS to create a connection. It works very well.
Please let me know what is the difference between these two kinds of WSDLs.
Without knowing what those links return we can only guess, but here are some details that might help you....
Suffixing the web service endpoint with ?wsdl get's you a WSDL file. The WSDL can be generated by the framework at runtime based on the web service skeleton code or can be an actual physical file that the server just sends back when the URL parameter is specified.
The WSDL contains an XML Schema that can be specified either inside the WSDL itself or as separate files that are imported by the WSDL. And now a problem occurs...
Some web service stub generators can only handle a full WSDL, with the Schema inside. If the WSDL imports other files the tools can't resolve the imports and fails. This made web services hard to consume because clients had issues creating stubs to interact with the web service. So much so that service providers either used an actual WSDL to respond to the ?wsdl request or started writing all sorts of hacks and plugins to make the web service generate the full WSDL.
But some providers didn't even bother so clients had to write the hacks to parse the WSDL or they had to download all files, assemble them manually into a single file and use that instead.
With time people recognized this as a problem and frameworks adapted to provide the full WSDL, not one with imports. But this generated another problem. Changing what the ?wsdl URL returned could break all those hacks created around it to fix the import problem. For this reason another convention was chosen to return the full WSDL: ?singleWsdl.
So there are frameworks that generate a full WSDL, some that generate it with imports, some allow you to specify an actual physical file, some that support the ?singleWsdl convention, some that don't. Not relevant to this question, but just for completion, there is also a ?wsdl2 convention that get's you a WSDL 2.0 definition (?wsdl get you a WSDL 1.1). Some frameworks support ?wsdl2, some don't.
My guess is the issues you have are caused by Schema imports, but without the WSDLs themselves I can't tell. Hope at least that these details help you better identify the problem.
What is the reason why hitting, for example, http:///_vti_bin/UserGroup.asmx?wsdl gives me a not full wsdl specification (if compared with http://msdn.microsoft.com/en-us/library/dd965659%28v=office.12%29.aspx)?
What I mean about not full: it does not contain some of complex types definition, e.g. User (unlike the full one), so this types are no generated by the wsdl.exe.
I have a question in regard of this: is it safe to generate c# web service stub basing on specification from MSDN or this approach is dangerous due to possible changes in contract?
For your first question as to the WSDL not being the same: it really should be equivalent and contain all the types! Whenever you append /_vti_bin/UserGroup.asmx?wsdl to your site's URL, SharePoint should definitely display the FULL WSDL, including the complex type definitions, etc. I just tried it now against my own SharePoint instance and the WSDL returned from http:// mysite.com/ ...snip... /pierre/_vti_bin/UserGroup.asmx?wsdl is pretty much the same size as the one from http://msdn.microsoft.com/en-us/library/dd965659%28v=office.12%29.aspx and a quick check to make sure complex types are in both places confirm that.
To answer your second question: I think you should NOT create your Web Service stubs and skeletons based on the WSDL in the documentation. Instead use the WSDL returned from your site. If you're not getting all the complex types in the WSDL returned from SharePoint, you should fix that issue first.
First thing I would try: download SOAPui (free) and simply plugin the URL that ends with ?wsdl and create sample requests. Maybe you'll run into access issues (UAG or other) but at least you'll know that the WSDL is well formed. If SOAPui can generate the client code based on the WSDL, you can too (using wsdl2java or the wsdl2dotnet equivalent; I can't remember the name of the .net version).
And yes, it's dangerous to copy the WSDL from the docs but I'd be more worried about some things being abbreviated or documentation going stale, etc.
As for the contract changing, I'm using the UserGroup.asmx?wsdl endpoint since 2009 and it still works on newer versions of SharePoint (even after the upgrade to SP2010). And I'm using java as the client code. Microsoft really nailed the Web Services in SharePoint, it was surprisingly easy to integrate our java stack and make calls to/from the SharePoint web services. And it was also very inter-operable with the other tools we use to test Web Services like SOAPui, etc.
We are developing an MDA platform that has support for Web Services. The user can provide a WSDL in runtime and we generate all the artifacts (service interface and implementation for the server, and consumer for the client) using JAX-WS internally.
We want to add validation on the WSDL document provided by the user. Right now the user has to validate that with an external tool like Oxygen, XMLSpy or a web tool, but we want to add that as a part of our system. A nice-to-have feature would be schema validation aswell, including the embedded schemas of the WSDLs.
In JAX-WS (RI) there is support for schema validation in runtime (using the #SchemaValidation annotation) but we haven't found any support for WSDL validation.
We've tried to integrate Eclipse's WSDL validator but it doesn't seem to work for us.
Is there any way of doing this with JAX-WS?
If not, is there any other validation framework that we can integrate?
Thanks
There is a bit of confusion in your question that I need to clarify first.
You seem to want the ability to validate the WSDL (syntax + WS-I) and XSDs, either embedded or referenced externally by the WSDL. On the other hand you bring in #SchemaValidation, which is actually used to validate instance documents.
In a traditional development approach, one might say you want at least the ability to validate design-time artifacts (WSDL+XSDs).
For this scenario then, I would recommend the following:
WSDL: for WS-I compliance testing, please take a look at the test tools section of the WS-I site. It is not clear how the licensing they have with their test tooling would work with yours, but at least it should give you an idea for what to look if it doesn't work for you.
UPDATE: Additional WSDL validation resources:
- Eclipse based, how to use outside Eclipse.
XSDs: if you really need separate validation for XSD files, things may get tricky for a production quality product; WSDL4J is not much help here, and I believe XSOM is the way to go for this kind of job. You have to extract content from the types section as one or more XSD files (could be more than one XSD file, take a look at some examples, Microsoft's SharePoint WSDLs come to my mind as a good test case), assign a base uri for each extracted XSD that matches the WSDLs location, then use XSOM to validate those.
Since you're generating the client, you're most likely not concerned with validating, say of the HTTP headers (SOAP 1.1/HTTP, SOAPAction, if it matches the WSDL operation definition). If you end up developing an interest in that as well, which I call runtime validation, then I would recommend a different layout in your approach (i.e. I would not rely on #SchemaValidation but rather do it through a transparent, and generic, proxy service).