One of our product publishes a webservice using contract-last approach. This has becoming a real problem as all of our clients (ws clients) have to rebuild their client apps as soon as we release a new version of our product. This is due to all namespace changes that comes as a cost with auto-generated wsdls. We use Axis1 for javatowsdl. I've been seeking for a good methodology/ tool to develop backward compatible webservice for this.
i.e. version 9.3 clients can still hit the 10.0 service, of cause they will miss some of the functionality, that is fine. But they should be able to function without breaking.
I do understand the whole problem is due to our contract last approach (Pls. correct me if I'm wrong). Therefore, if the solution is to go for contract-first webservice what are the tools and technologies I could use? Also what are the best practises around contract-first?
Thanks in advance.
As you already realized, the recommendation is to use a Contract-First (or Top-Down) approach to develop Web Services. That implies a manual definition of your WSDL interface and generate a Java Skeleton of the Web Service based on this document using automatic tools.
Is important that your WSDL complies to the WS-I standart to assure interoperability between clients on different platforms. You can use SOAP-UI to test whether your WSDL is compatible with the standard or not.
For the Skeleton generation, there are several Web Service Runtime API's that you can use: Like Apache Axis and JAX-WS. I personally prefer JAX-WS because is a Java Standard and is supported by all Java EE Containers. Each container provides tools for the Skeleton generation, Weblogic has some nice Ant Task for that but there's also WS-Import that is Container neutral.
I have a project where I have kept web service in two separate package. One package contain customer face web services and another contains in house usage web services. I want jersey to only scan the customer facing package and generate WADL.
In general I was not able to find any way to split wadl generation logic by configuration. But here is hack you can perform. There is class called GenerateWadlTask.java This basically does the wadl generation logic for jersey. You can just extend this class in your custom application wadl generation task and use it as per your logic. For code example just download the jersey server source jar and look at the class. The logic is pretty straight forward.
hope this help.
EDIT:- There is a maven plugin called enunicate http://enunciate.codehaus.org/
That will make your life easy.
I'm looking for an alternative to the awesome .NET (WCF) REST capabilities.
Why?
I have deep interest in open source technology, but when it comes to webservices I do not have any experience except with .NET webservices.
Besides, I'm currently using a lot of Java and Python, and I am moving away from the Microsoft technology stack.
Please suggest alternatives in any programming language, but explain why it's good or better for some reasons. (this reason may be be tightly related with the choice of language)
What do I want to know?
Ease of use
Installation
Configuration
Generation capabilities
IDE integration
Deployment
Learning curve
Pros and cons
etc.
Spring 3.0 REST:
Spring uses annotation based controllers, which can be used to bind a url to a method in the controller. Annotations are used to differentiate between GET methods and POST methods.
#RequestMapping(value="/hotels/{hotel}/bookings/{booking}",
method=RequestMethod.GET)
public String getBooking(#PathVariable("hotel") long hotelId,
#PathVariable("booking") long bookingId, Model model) {
Hotel hotel = hotelService.getHotel(hotelId);
Booking booking = hotel.getBooking(bookingId);
model.addAttribute("booking", booking);
return "booking";
}
Under the hood, the variable "hotel" in the URI string is converted to a long in the parameter list, as is booking. Spring REST can also marshal JSON objects into custom classes using this same technique. Note that this method is annotated as RequestMethod.GET, which means it's invoked for GET requests but not POST requests.
Spring 3.0 REST makes it easier to create RESTful Web services by eliminating the need to reinvent the wheel or marshal/unmarshal JSON text by hand from/to Java objects.
There is a demo here on the SpringSource Blog titled REST In Spring MVC. The learning curve is low, but getting the demo to work may take some time thanks to dependencies. Once you get setup and have a working demo, the hardest part should be over.
For IDE integration, check out Spring Roo. I've not used it, but I've heard it has some features that integrate with Eclipse IDE to make your life easier.
Restlets:
Restlets were designed solely for REST. As a result, the overhead is a lot lower than Spring 3.0. Restlets are better suited for cases where you don't have a GUI, and where you aren't concerned with MVC. Restlets can easily serve as both a server and a client. It also has an embedded server you can run, which eliminates the need for a container like Jetty or Tomcat.
I've had very little exposure to Python, but from what I've seen of Google App Engine's implementation of the webApp framework, the Router concept feels very similar. Those with a Python background may find the learning curve to be a lot lower:
#Override
public Restlet createInboundRoot() {
Router router = new Router(getContext());
getConnectorService().getClientProtocols().add(Protocol.FILE);
// Serve the files generated by the GWT compilation step.
Directory dir = new Directory(getContext(), LocalReference.createFileReference(new File("war/")));
router.attachDefault(dir);
router.attach("/contacts/123", ContactServerResource.class);
return router;
}
It uses GWT on the client-side; I prefer to take that part out as it reminds me too much of Java Swing. While some people may find that advantageous, my personal preference is to stick with the technologies that feel more like the Web.
Below is a simple example of a REST server using the standalone mode. The server runs on port 8182, and it listens for GET requests. It has a similar annotation-based model as the Spring REST framework, which also helps split up the different HTTP methods and point them at different methods in your classes. This is a very basic "Hello World" REST example:
public class FirstServerResource extends ServerResource {
public static void main(String[] args) throws Exception {
// Create the HTTP server and listen on port 8182
new Server(Protocol.HTTP, 8182, FirstServerResource.class).start();
}
#Get
public String toString() {
return "hello, world";
}
}
Check out the Restlet Web Site for more information and examples of the Restlets framework. Restlets has a slightly less learning curve than Spring because it's targeted to REST; as a result, it doesn't contain all of the extra functionality included with Spring that can sometimes make finding an answer to a problem difficult. Restlets are definitely the way to go if you're looking for something lightweight.
Both of these two frameworks will run in Tomcat, Jetty, as well as on Google App Engine.
If you are using Java and you are familiar with Spring, then you should certainly take a look at Spring MVC 3.x. This version moves away from the ugly XML configuration, and its syntax is very similar to JAX-RS's specs. That said, if you know Spring, then learning Spring MVC 3.0 is going to be minimal. However, if you are having trouble understanding with IoC pattern and what not, then it is going to be a long painful experience. :)
Keep in mind, Spring MVC 3.x is not pure REST, and it will never be in the future at all, based on the Spring MVC developers. Their take was there are already so many good REST implementations and there's no point of making Spring MVC 3.x totally RESTful.
Another option I will certainly recommend to you is Jersey. Jersey is pure REST, in another word, it is an implementation of JAX-RS. Jersey took me 30 minutes to learn. In my opinion, the annotations are so much more powerful and richer than Spring MVC 3.x. The annotations from Spring MVC 3.x seem pretty vanilla to me. Jersey will automatically generate the WADL for you, although it is pretty basic... but having one is better than not having one. You can certainly customize your WADL if you want. (By the way, WADL is REST's version of WSDL, if you don't know what that means). Jersey basically detects your package containing all the Resource classes and generates the WADL based on the configurations you have, pretty neat stuff. The last thing I want to point out is Jersey has a great test framework for you to easily test your Restful web service. In another word, their test framework allows your unit test to easily fire up Grizzly or in-memory server to test your web service. It is certainly one of the best I have ever use thus far. Here's a very easy tutorial for you get your feet wet: http://www.vogella.de/articles/REST/article.html . It is really THAT easy. :)
FYI, I have used both Spring MVC 3.x and Jersey.
ServiceStack is one of the more recent developments. I haven't done much with it yet, but it seems pretty sweet so far.
Ruby and Rails (Ruby on Rails) have great support for RESTful service. In fact Rails supports and encourages design and develop in RESTful manner.
Thanks to ruby's strong DSL feature, writing REST service is very straightforward and easy. Since you have python experience, learning ruby might be easy.
Refer to this guide to have an impression how rest urls (called routes in rails) are defined.
Other Ruby web frameworks such as Sinatra also do a good job on this.
BTW, the best things is that both ruby and rails are open source, and the ruby community is awesome and very active.
There's RESTSharp as a REST/HTTP client (open-source project) and OpenRasta
I welcome you to check out servicestack.net it is designed for simplicity and speed and introduces very low artificial concepts where it is able to maintain a very DRY and succinct API and automatically works out of the box without any configuration or code-gen.
It encourages best practices as it is modelled around Martin Fowlers Gateway and DTO pattern for developing remote services.
The equivalent code for the Spring.NET example above would be
Configuration (in AppHost)
Routes.Add<Booking>("/hotels/{HotelId}/bookings/{BookingId}");
C# Code
public class BookingService : RestServiceBase<Booking>
{
public IHotelService hotelService { get; set; } //auto-injected by IOC
public object OnGet(Booking request)
{
var hotel = hotelService.GetHotel(request.HotelId);
var booking = hotel.GetBooking(request.BookingId);
return booking;
}
}
A similar example to the booking service can be seen by the live Northwind Web Services demo.
That's all the configuration and code (exc DTO) you need to write for that service and it is automatically available via JSON, XML, JSV, CSV, SOAP 1.1/1.2 and HTML endpoints and formats automatically without any extra configuration required.
Checkout the Hello World example for more info on all the endpoints and formats provided as well as the auto generated /metadata and documentation pages.
There is an open source framework entirely developed for RESTful web services which is called Recess
It's not very old, but got good attention from the industry. Alcatel-Lucene already arranged a competition on TopCoder for developing some of their services using this framework.
Check out details at Recess web site
I am a noob to web services world. I need to develop a login validator module and expose it as a service. I want it to be service independent, i.e I should have the option of exposing it as a SOAP service or REST service in the future.
What pattern should I follow ? Sorry if I am unclear in my requirements, I can clarify as per need.
Thanks !!
Edit : I am using Eclipse as an IDE and Jersey libraries. I am not into any framework, simply using the MVC pattern. I find a lot of difference between SOAP ann REST methods, so I want my methods to be implementation independent - i.e I should be easily able to use my method through a SOAP or REST service call as per need. What should I do for maximum flexibility ?
Picking a good MVC framework and understanding how to use it properly can help ensure that your feature is "service independent". Most of the documentation I've read for good frameworks suggest that you keep your business logic separate from your controller.
If you read the documentation for the tools that you use, and ensure that there is a layer between your business logic and your controllers, then that will make the job of switching from SOAP to REST or some other protocol much, much easier.
Since you mentioned you're using Eclipse in your comment below, I'm assuming you are using or are willing to use Java:
Restlets
http://www.restlet.org/
Spring 3.0 REST
http://blog.springsource.com/2009/03/08/rest-in-spring-3-mvc/
Develop your service as a POJO. Make sure to respect staless pattern.
Create an EndPoint class for each publication type you require (Soap, Rest, EJB, JMS, what ever)
Use appropriate standard to expose your EndPoint. For Soap and Rest the JAX-WS api and implementations can do it for you using java annotations on your EndPoint.
That's it !
I have build plenty of SOAP webservices, but am building a REST webservice for a specific project, and I was wondering what people used for a 'WSDL' for REST services or if it is even needed.
You can try Swagger(now OpenAPI) which allows to describe REST services using a JSON open standard.
REST really only uses the HTTP verbs (GET,PUT,POST,DELETE) on a resource. All operations on a resource are supposed to be represented that way. POST is used as a catch all for when you can't express your business logic in a way that fits into the other three. That is why there isn't really a WSDL for a REST service since you only ever have 4 methods on the resource. Note that the Zend Framework REST library isn't really RESTful and is more of a plain old XML (POX) service.
While Sam's correct that RESTful web applications don't need a direct analog to WSDL, there is an XML vocabulary that's useful for describing RESTful web apps: WADL, or Web Application Description Language. At my company we primarily use WADL to define a spec for a given service that we want to build - we don't generally use it programmatically. That said, the WADL home page includes some Java tools for code generation, and Restlet, the Java REST framework, includes a WADL extension for dynamically wiring applications based on WADL and dynamically generating WADL based on a wired application. I'm a fan of WADL, and recommend that you check it out.
Actually it's possible to use WSDL for that but it should be v 2.0 - see "Describe REST Web services with WSDL 2.0" article.
You can supply an XSD if you are using XML in your REST service.
Or just examples of the XML, should be enough to work things out for simple data structures anyway.