将现有 API 作为 Web 服务公开 [英] Exposing existing API as a Web service

问题描述

我目前正在处理一项将 API 公开为 Web 服务的任务.这里的想法是将 JAR 文件中的现有业务逻辑打包到一个 WAR 文件中，并将该 WAR 文件公开为一个 Web 服务，该服务将返回一个自由格式的 XML 字符串.当我们将现有 API 作为 Web 服务公开时，我们提供 XSD & 是否足够?返回的 XML 字符串数据的 WSDL 文件?这是惯例还是标准做法?

I am currently working on a task to expose an API as a Web service. The idea here is to package the existing business logic in JAR files into a WAR file and expose the WAR file as a Web service that would return a free-form XML string. When we expose an existing API as a Web service, is it sufficient that we make available an XSD & WSDL file of the returned XML string data? Is that the convention or the standard practice?

推荐答案

这取决于您使用的是 SOAP 还是 REST.SOAP 限制更多；因此，更希望您拥有一个 WSDL 文件来生成与 API 接口的类.

It depends on whether or not you are using SOAP or REST. SOAP is more restrictive; as a result, it's more expected that you'll have a WSDL file to generate the classes that interface with the API.

另一方面，如果您使用的是 REST，则认为仅公开 RESTful URI 就足以满足具有统一接口的 RESTful Web 服务的约束.

On the other hand, if you are using REST, just exposing a RESTful URI would be considered enough to meet the constraint of a RESTful web service having a uniform interface.

REST 比 SOAP 更受欢迎，因为它是一种宽松的架构风格.我更喜欢这种方法，如果您刚开始开发 Web 服务，我会推荐这种方法.

REST tends to be gaining more ground over SOAP since it is a permissive architectural style. I would prefer this method, and I would recommend this method if you're new to developing web services.

根据您使用的语言，我假设您使用 Java，您可以使用 Restlets 或 Spring 3.0 的 REST 框架来帮助您构建 RESTful Web 服务.这些工具确实让这项工作变得更容易，并帮助您遵守 6 RESTful Web 服务的约束 并满足 4 个关键目标.

Depending on what language you are using, I'm assuming Java, you can use Restlets or Spring 3.0's REST framework to help you build a RESTful web service. These tools really make that job a lot easier and help you conform to the 6 Constraints of a RESTful Web Service and meet the 4 Key Goals.

更新:

假设您已经拥有现有的面向对象的代码，并假设您想将该代码公开为 REST API，使用 Spring 3.0 MVC，创建一个将环绕现有包的 Controller 子类:

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

示例 GET:

资源:Jackson 的 ObjectMapper POJO 的 Javadocs/JSON 编组器

 // 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; }
}

请求:

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

回复:

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

XML 而不是 JSON:

返回 XML 和返回 JSON 的主要区别在于所使用的编组器.使用 javax.xml.bind.annotations，您可以在 POJO 类上放置注释，以便编组器可以将其转换为 XML，从而使您无需手动编写 XML 代码:

The main difference between returning XML and returning JSON is in the marshaller used. Using javax.xml.bind.annotations, you can place annotations on the POJO class so the marshaller can convert it to XML, freeing you up from the details of having to manually code XML by hand:

使用 javax.xml.bind.annotations 将 Java 对象转换为 XML 和 XSD.此资源还说明了如何生成 XML 架构(如果您认为这是 REST Web 服务的要求).

Using javax.xml.bind.annotations to convert Java Objects to XML and XSD. This resource also explains how to generate the XML Schema, if you deem that as a requirement to 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; }
}

不要使用 Jackson API 的 ObjectMapper 类将 POJO 类编组为 JSON，而是使用 javax.xml.bind.annotations 包代替 ObjectMapper:

Instead of using the Jackson API's ObjectMapper class to marshal the POJO class to JSON, use the javax.xml.bind.annotations package in place of ObjectMapper:

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);

除了其他资源，本文还有一些使用 JAXB 将 POJO 对象的 ArrayList 反序列化为 XML.

Aside from the other resources, this article has a few examples that use JAXB to deserialize an ArrayList of POJO objects to XML.

我在处理 REST Web 服务包装器时的最后建议是将日志记录级别设置为ALL"或DEBUG".我发现这有助于我更轻松地确定设置 Web 服务时遇到的任何问题的根本原因.库本身将输出有用的调试消息，以帮助您解决配置问题，例如缺少依赖项、缺少注释以及在处理到 XML/JSON 过程的转换或设置 Spring 3.0 时可能遇到的其他问题.

My final suggestion when working on the REST Web service wrappers is to set your logging levels to "ALL" or "DEBUG". I find that this helps me more easily determine the root cause of any problems I face when setting up a Web service. The libraries themselves will output helpful debug messages to help you resolve configuration issues, such as missing dependencies, missing annotations, and other issues that you'll likely encounter when dealing with the conversion to XML/JSON process or in setting up Spring 3.0.

设置统一接口后，您可以发出 GET 请求并接收响应，然后您可以将日志记录级别设置回之前的 INFO 或 WARN 级别.

Once you're uniform interfaces are setup and you can make GET requests and receive responses, you can then set the logging levels back to the previous INFO or WARN levels.

这篇关于将现有 API 作为 Web 服务公开的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！