Providing an Existing API as a Web Service

Question

I am currently working on the task of exposing the API as a web service. The idea here is to pack the existing business logic in the JAR files into a WAR file and provide the WAR file as a web service that will return a free form XML string. When we show the existing API as a web service, is it enough for us to provide an XSD and WSDL XML string return file? Is it a convention or standard practice?

Answer 1

It depends on whether you use SOAP or REST. SOAP is more restrictive; as a result, it was expected that you would have a WSDL file to create classes that interact with the API.

On the other hand, if you use REST, just looking at the RESTful URI will be considered sufficient to satisfy the restriction of the RESTful web service having a single interface.

REST tends to gain more opportunities for SOAP, as it is a permissive architectural style. I would prefer this method, and I would recommend this method if you are new to web services development.

Depending on which language you use, I assume Java, you can use the Restlets or Spring 3.0 REST framework to help you create a RESTful web service. These tools really make the job easier and help you meet the 6 limitations of the RESTful web service and meet 4 key goals .

UPDATE:

Assuming you already have existing object-oriented code and assume that you want to present this code as a REST API using Spring 3.0 MVC, create a subclass of Controller that will wrap your existing package:

GET example :

Resource: Javadocs for Jackson ObjectMapper POJO / JSON Marshaller

// this is the wrapper around your existing Java packages. @Controller public class UserController { protected static final DATA_TYPE = "json"; // In REST, GET method is used to retrieve data with no side effects, // meaning that no changes are made to the data on the server. @RequestMapping(value="/users/{username}", method=RequestMethod.GET) public void getUserData(@PathVariable("username") String userName, Model model) { // this is your existing class UserDataService userDataService = new UserDataService(); // assume you have a class User, and getUserDetails gives you that POJO object. User user = userDataService.getUserDetails(username); // marshal the User object to JSON, using Jackson, and write as output in response ObjectMapper mapper = new ObjectMapper(); mapper.writeValue(response.getWriter(), user); } } // assume you have an existing POJO class called User class User implements Serializable { String username; String age; String birthday; String mood; String getMood() { return this.mood; } String getBirthday() { return this.birthday; } String getAge() { return this.age; } String getUsername() { return this.username; } String setMood(String mood) { this.mood = mood; } String setBirthday(String birthday) { this.birthday = birthday; } String setAge(String age) { this.age = age; } String setUsername(String username) { this.username = username; } } 

Request

 http://api.example.com:8080/users/jmort253/ 

Answer:

 { "username":"jmort253", "mood":"good", "age":"not too old and not too young", "birthday","Jan 1, 1900" } 

XML instead of JSON :

The main difference between XML return and JSON return is the marshaller used. Using javax.xml.bind.annotations, you can put annotations in the POJO class so that the marshaller can convert it to XML, freeing you from the details of the need manually manually manually XML:

Using javax.xml.bind.annotations to convert Java objects to XML and XSD . This resource also explains how to generate an XML schema if you think it is necessary for your REST web service.

  @XmlRootElement class User implements Serializable { String username; String age; String birthday; String mood; String getMood() { return this.mood; } String getBirthday() { return this.birthday; } String getAge() { return this.age; } String getUsername() { return this.username; } String setMood(String mood) { this.mood = mood; } String setBirthday(String birthday) { this.birthday = birthday; } String setAge(String age) { this.age = age; } String setUsername(String username) { this.username = username; } } 

Instead of using the Jackson ObjectMapper API class to marshal the POJO class for JSON, use the javax.xml.bind.annotations package instead of the ObjectMapper package:

 JAXBContext context = JAXBContext.newInstance(User.class); Marshaller marshaller = context.createMarshaller(); // pretty print XML marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true); marshaller.marshal(user, System.out); 

Among other resources, there are several examples in this article that use JAXB to deserialize ArrayList POJO objects for XML .

My last suggestion when working with REST web services wrappers is to set the logging levels to "ALL" or "DEBUG". I believe that this helps me more easily determine the root cause of any problems that I encounter when setting up a web service. The libraries themselves will provide useful debugging messages that will help you solve configuration problems, such as missing dependencies, missing annotations, and other problems that you may encounter when accessing the XML / JSON process or when configuring Spring 3.0.

After you configure the same interfaces, and you can make GET requests and receive responses, you can set the logging levels to the previous INFO or WARN levels.

Answer 2

First of all, I would be embarrassed before exposing the existing API as a one-to-one web service. Was there access to an existing API to access over the network? If not, then it probably wasn’t designed with network limitations in mind.

It can include method calls, which will include more small operations — a type that costs nothing when used in a single process. Over the network, each call has an associated delay, which is much greater than the overhead of casting a method within the same process.

Instead, I would develop a service to meet the functional requirements of the API. The service is likely to be designed for fewer operations that do more work per operation, thereby minimizing the overhead associated with network traffic. The service is likely to be implemented by calling the API (provided that it is written to handle multithreaded environments such as a service).

In terms of WSDL, the tools you use can very well build the WSDL for you. I know that WCF in .NET does this, and I did the same with IBM Rational Web Developer, so I know that the Java world can do the same.

Otherwise, in fact it is not so difficult to write WSDL and the corresponding scheme. In any case, they should be provided in such a way that your customers can use this service.

There is nothing wrong with using REST for this if your API can be clearly expressed as a set of resource operations. In this case, yes, provide a schema to make XML processing easier for your clients. I would not force your API to conform to the REST model if it is not purely expressed, like resource operations.