Developing Web services

Web services are self-contained applications, based on open standards, that can be invoked over the Web. Web services provide a way for applications to connect and interact easily and efficiently. They can be building blocks of applications used within your enterprise or provide a point of interaction with other enterprises. Because their interfaces are defined according to standards, Web services can interact with other applications that are not Java-based.

You can use HATS Web service support to create service-oriented architecture (SOA) assets that provide standard programming interfaces to business logic and transactions contained within your host applications. These core business tasks can be reused as standard Web services that participate as an integral part of your business process integration plan. Use your core business services as building blocks to develop new internal applications or to integrate with applications outside your enterprise. Your host-based business tasks can then be included in your SOA solutions with IBM® SOA Foundation products, such as IBM WebSphere® Process Server, IBM WebSphere Enterprise Service Bus, and others.

Using a combination of tools from HATS Toolkit and Rational® SDP, you can create Web services from Integration Objects or from EJB Access Beans. With HATS you can create traditional Web services defined by Web Services Description Language (WSDL) files as well as Representational State Transfer (RESTful) Web services.

Note:
You cannot use an Integration Object that is configured to use Web Express Logon in a Web service.

Traditional Web services use several standard ways to formulate information: Simple Object Access Protocol (SOAP), Web Service Description Language (WSDL), Universal Description, Discovery, and Integration (UDDI). This book refers to but does not explain these protocols. You can find information about them by opening the Rational SDP documentation (click Help > Help Contents from any Rational SDP perspective) and searching for Web service.

RESTful Web services provide an alternative to the traditional WSDL-style Web service implementation and may be more appropriate for your particular needs. RESTful Web services use HTTP instead of SOAP, and may require less bandwidth, which may be useful for devices like mobile phones and PDAs. In addition, use of the HTTP caching infrastructure (with the HTTP GET method) may improve performance for data that can be cached.

Note:
Traditional Web services may continue to be more appropriate for cases where a formal description (the WSDL file) of the Web service interface must be established.

RESTful Web services use a stateless architecture and are viewed as resources rather than function calls. They use well-formatted URIs to identify resources, use HTTP method protocols to do create, retrieve, update, and delete (CRUD) activities, and use HTTP header information to define the message formats. For more information about RESTful Web services, see the Rational Business Developer Knowledge Center at http://www.ibm.com/support/knowledgecenter/SSMQ79 and search for Architectural styles in web services.

Usually you create HATS Web services from Integration Objects that you have already built, tested, and deployed. This chapter assumes that you have one or more successfully tested Integration Objects that you want to include in a Web service. However, you can start from the very beginning by opening your host terminal, recording one or more macros, creating Integration Objects from the macros, and testing the Integration Objects. Refer to HATS User's and Administrator's Guide for information about creating an Integration Object from a macro.

Creating traditional (WSDL-based) Web services

You must decide whether you want your Web service to comply with the Web Services Interoperability (WSI) standard. This will govern which Web service runtime you use for the creation of your Web services. If you accept the default, IBM WebSphere runtime, the resulting Web service will be WSI-compliant.

You must follow certain naming conventions when creating Web services using IBM WebSphere runtime. These include:

Keep these naming restrictions in mind when creating macro names, prompt names, and extract names during macro creation. For more information on naming restrictions, refer to the Rational SDP documentation.

Creating a Bottom-up Web service from Integration Objects

The instructions in this section assume that you want to create a Web service that has input and output properties and methods similar to all of the properties and methods in an Integration Object. Or, in other words, you want the signature of the Web service that you create to be similar to that of an Integration Object contained in the Web service. This scenario is called a Bottom-up Web service.

To create a Web service, begin from the HATS Projects view and follow these steps:

  1. Expand the project that contains the Integration Objects you wish to use, then expand the Source folder and the IntegrationObject folder.
  2. Right-click any Integration Object in your project and select Create Web Service Support Files.
  3. The Create Web Service Support Files wizard enables you to select any project as the source of the Integration Objects you will include in a Web service. The project in which you clicked will be the default. Provide a class name for the HATS Web service support files. The class name must begin with an uppercase letter. This class is referred to as your wrapper class for this Web service. This wrapper class enables you to select a logical group of Integration Objects or EJB Access Beans to include in one Web service. For example, you might select to include all the Integration Objects in a chain in the wrapper class. To see a list of Integration Objects and select the ones to include, click Next.
  4. Select the resources (Integration Objects and EJB access beans) that you want to include in your Web service. If you want to change the input and output properties that are exposed by the Web service for a given resource, select the resource and click Properties.
  5. On the Choose Properties page, select the input and output properties that you want exposed in the Web service. If you wish, you can provide an alias name for the property in the Alias Name field. Use the Select All, Deselect All, and Select Default buttons to help in selecting the properties. Click OK.
    Notes:
    1. Defaults for single Integration Objects and EJB access beans are all macro prompts for input properties and all macro extracts for output properties.
    2. Defaults for chained Integration Objects are all macro prompts plus hPubLinkKey (which is required) for input properties and all macro extracts plus hPubLinkKey (which is required) for output properties.
    3. Defaults for chained EJB access beans are all macro prompts plus hPubLinkKey and hPubAccessHandle (both of which are required) for input properties and all macro extracts plus hPubLinkKey and hPubAccessHandle (both of which are required) for output properties.
    4. To specify that Integration Object connection overrides be exposed to the Web service, you must select the appropriate properties, for example the hPubConnectionOverrides or hPubStartPoolName properties, which are not selected by default. For more information, see Specifying Connection Overrides.
    5. For more information about the use of other Integration Object methods, see Programming with Integration Objects.
    6. For considerations when using bidirectional language support, see Support of bottom-up Web services in the HATS User's and Administrator's Guide.
  6. Click Finish. HATS creates a set of classes to be used in creating the Web service. The following classes appear in the HATS Projects view in the Source\webserviceclasses folder:
  7. At this point, you are ready to create a Web service using the tools provided in the IBM Rational SDP. Familiarize yourself with the procedure and the options available to you by reviewing the Bottom-up Web services development chapter. At a minimum, you should start the server that you are going to deploy the Web service to before continuing to create the Web service. These instructions assume that you are going to use separate steps to create your Web service, test your Web service, and create your Web service client.
  8. Expand the webserviceclasses package. Right-click the wrapper class that you created, and select Web Services > Create Web service. The Web service type defaults to Bottom up Java™ bean Web service. Make sure that you keep this default. You can click Finish here or select other options that best meet your requirements, as described in the Rational SDP documentation. If you select the option, Generate WSDL file into the project, Rational SDP creates a Web Services Description Language (WSDL) file that describes the interfaces to your Web service. You can use this WSDL file to test your Web service using the Web services explorer in the HATS project view. If you do not select this option, you can use a dynamically generated WSDL file to test your Web service from Services view of the Java EE perspective. When you have made all your choices, click Finish.
  9. Go to Testing your Web service with Web Services Explorer for information about testing your Web service before you create a client.

Testing your Web service with Web Services Explorer

You can test your Web service in Rational SDP before you create a client application.

Before you start this process, ensure that the HATS runtime is started. You can do this by starting your server, and then, in the Servers view, choose the EAR file in which your Web service is contained, right-click, and choose Restart.

If you selected the option to Generate WSDL file into the project, see step 8 in the list under Creating a Bottom-up Web service from Integration Objects, the WSDL file that you created is located within your HATS project:

This folder contains a file called wrapper.wsdl, where wrapper is the name you gave to your wrapper class. Right-click this file and select Web Services > Test with Web Services Explorer.

In the right pane of the Web Services Explorer, you will see the io_nameProcessWS() methods for each Integration Object or EJB Access Bean included in the Web service. Click any method name to test that Integration Object. You will see a list of the input properties that you can specify for the Integration Object. This list is based on the Integration Object's io_name_Input_Properties class. The only properties that must be set are the prompts that you defined when you recorded your macro. The other properties can be left blank. Refer to the Rational SDP documentation for information about using the WSDL view of Web Services Explorer to explore and test your Web service definition.

If you did not select the option to Generate WSDL file into the project, see step 8 in the list under Creating a Bottom-up Web service from Integration Objects, you can use a dynamically generated WSDL file to test your Web service from Services view of the Java EE perspective.

Creating a Web service client

Next you can create a client application to use the Web service. Do the following:

  1. Expand your project, then expand the folder appropriate for the Web service runtime you selected when you created the Web service. The WSDL file that you created is located within your HATS project: This folder contains a file called wrapper.wsdl, where wrapper is the name you gave to your wrapper class.
  2. Right-click this file and select Web Services > Generate Client to start the Web Service Client Proxy wizard. On the first page of the wizard, you can choose all defaults except for the client project. You should choose a project other than the project that contains the Web service.
    Note:
    The specified Client project and the Ear project need to have the same server target as the chosen Server.
    You can click Finish at this point, or continue through the wizard. Refer to the Rational SDP documentation for information about the options in this wizard.
  3. If you chose to Test the Web service, the wizard creates sample JSP pages, and runs the sample on the server. The output of the sample JSP pages will be displayed in the web browser. To run the sample, in the Methods frame, click the io_nameProcessWS link to test a particular Integration Object or EJB Access Bean. In the Inputs frame, set the required inputs, as described in Testing your Web service with Web Services Explorer. The Result frame will display the outputs.

    The sample pages are created in your client project. In the Navigator view, expand your client project, and expand Web Content and samplewrapperProxy. In the samplewrapperProxy folder are the sample JSP pages. You can run the sample by running the TestClient.jsp file on the server. Double click Result.jsp to open it in the JSP editor. You can examine the code and copy code from the sample into a HATS business logic class, which can be run from a screen customization to invoke your Web service and use the output in a transformation or in some other way.

Creating a Top-down Web service that includes Integration Objects

Your development task may involve creating a top-down Web service, where you have been given a WSDL that has the specified signature of the Web service. Your task is to create the Web service implementation, part of which involves interacting with an existing terminal application.

If the input parameters in the WSDL either contain the required input properties for an Integration Object, or based on the input parameters, you can write code that will set the required Integration Object input properties, you can use Integration Objects directly in your Web service implementation.

The Rational SDP contains tools to create a skeleton Java bean from an existing WSDL. You can then interact with Integration Objects directly from this skeleton Java bean. Refer to Programming with Integration Objects to learn more. The one caveat is that you should use the processRequest () method to invoke the Integration Object in a Web services run time environment.

Refer to Introduction

Programming with Web Services Integration Objects and EJB Access Beans

Integration Object chaining with Web Services

If your application requires chaining, your client code must retrieve the hPubLinkKey property from the first Integration Object in the chain, and set it for all subsequent Integration Objects in the chain.

EJB Access Bean chaining with Web Services

If your application requires chaining, your client code must retrieve both the hPubLinkKey and the hPubAccessHandle properties from the first EJB Access Bean in the chain, and set them for all subsequent EJB Access Beans in the chain.

Special considerations with chaining Web Services

If you use chained Integration Objects within a HATS Web service, you are creating a stateful Web service. HATS runtime does not store data between invocations of chained Integration Objects in the same Web service. However, HATS runtime does require that the next in chain Web service invocation is routed back to the same instance of the HATS runtime so that the next in chain IO will use the same Telnet connection.

If you deploy a stateful HATS Web service using JAX-RPC support to a cluster, to enable all Integration Objects in the chain to use the same Telnet connection, do one of the following:

If you deploy a stateful HATS Web service using JAX-WS support to a cluster, to enable all Integration Objects in the chain to use the same Telnet connection, do one of the following:

Updating Web services

The Update wizard is only enabled for Web service classes that have been created with HATS 7.0.0.2 or later. If you are using an earlier version, then you must update manually.

To update the HATS Web service support classes, do the following:

  1. Select an existing Web service wrapper class to update.
  2. The Update Web service wizard is invoked with the Web service class preselected.
  3. If you do not need to change the selection of Integration Objects or EJB Access Beans included in the Web service, you can select Finish to regenerate the Web service support classes, otherwise select Next to continue to the next page of the wizard.
  4. Modify the list of resources (Integration Objects and EJB access beans) included in the Web service wrapper class . If you want to change the input and output properties that are exposed by the Web service for a given resource, select the resource and click Properties.
  5. On the Choose Properties page, select the input and output properties that you want exposed in the Web service. If you wish, you can provide an alias name for the property in the Alias Name field. Use the Select All, Deselect All, and Select Default buttons to help in selecting the properties. Click OK.
    Notes:
    1. Defaults for single Integration Objects and EJB access beans are all macro prompts for input properties and all macro extracts for output properties.
    2. Defaults for chained Integration Objects are all macro prompts plus hPubLinkKey (which is required) for input properties and all macro extracts plus hPubLinkKey (which is required) for output properties.
    3. Defaults for chained EJB access beans are all macro prompts plus hPubLinkKey and hPubAccessHandle (both of which are required) for input properties and all macro extracts plus hPubLinkKey and hPubAccessHandle (both of which are required) for output properties.
    4. To specify that Integration Object connection overrides be exposed to the Web service, you must select the appropriate properties, for example the hPubConnectionOverrides or hPubStartPoolName properties, which are not selected by default. For more information, see Specifying Connection Overrides.
    5. For more information about the use of other Integration Object methods, see Programming with Integration Objects.
    6. For considerations when using bidirectional language support, see Support of bottom-up Web services in the HATS User's and Administrator's Guide.
  6. Click Finish.

The HATS Web service support files are regenerated and compiled. Note that you still must use the Rational SDP wizards to update your Web services once you have updated the HATS Web services support files.

Web services for JAX-WS runtime considerations and limitations

If you plan to create HATS Web services for the JAX-WS runtime, be aware of the following:

Creating RESTful Web services

As with traditional Web services, RESTful Web services are created from HATS Integration Objects and their input and output properties. With traditional Web services, you define the location and input and output properties of the Web service resources in a WSDL file. However, with RESTful Web services, you define access to the Web service resources using URIs to represent the resources, HTTP methods to operate on the resources, and HTTP header information to define the message formats.

In the following figure is an architectural view of HATS support for RESTful Web services.

  1. The HATS RestServlet receives from a client an HTTP request with URI and an HTTP method.
  2. The RestServlet routes the request by mapping information in the URI and the HTTP method to a JAX-RS resource for an Integration Object.
  3. The JAX-RS resource receives the request, reads the parameters in the request, initializes the Integration Object, sets prompts (input properties), and runs the Integration Object.
  4. The JAX-RS resource receives extracts (output properties) from the Integration Object, generates a response, and returns it to the RestServlet.
  5. The RestServlet responds to the client.
Figure 20. HATS RESTful Web service architecture
Note:
To run a HATS Integration Object, the client must call one Integration Object at a time. For chained Integration Objects, the client must call one Integration Object, then call the next, passing the link key, or you must modify the wrapper to call one Integration Object after another, passing the link key.

HATS provides tools you can use to create JAX-RS resources for your Integration Objects, and mappings so that URIs and HTTP methods in HTTP requests can be mapped to the correct JAX-RS resources.

Creating RESTful service JAX-RS resources

To create a JAX-RS resource for an Integration Object, in the HATS Projects view:

  1. Expand the project that contains the Integration Object you wish to use, then expand the Source folder and the IntegrationObject folder.
  2. Right-click the Integration Object and select Create RESTful Service Files. The Create RESTful Service Files wizard opens.
  3. On the Specify JAX-RS Resource class name and Integration Object page, in the Name field, specify the name of the JAX-RS resource class to generate in the Source folder. The name must follow generic Java class name syntax.
  4. Optionally select whether to Overwrite resources without warnings.
  5. Click Next.
  6. On the Configure JAX-RS Resource class page, in the URI Suffix field, specify a suffix to create the complete URI to use in mapping to your JAX-RS resource. For example, if the host where the HATS RESTful service is installed is www.myHost.com, the HATS project (application) name is myApp, and the URI Suffix is mySuffix, then the resulting URI for the JAX-RS resource is http://www.myHost.com:9080/myApp/rest/mySuffix.
    Note:
    The combination of URI plus HTTP method must be unique among all of the JAX-RS resources that you define. If not, the JAX-RS runtime picks only one of the resource functions to invoke based on a priority algorithm using the combination of consumes and produces content types (see Customizing RESTful service JAX-RS resource methods).
  7. By default, Enable Swagger is selected. You can disable it if you do not want to include Swagger support. By selecting Copy URI Suffix to Swagger Api Value, you can automatically copy the URI Suffix value to the Swagger Api Value field. To enter a new value, you can uncheck the Copy URI Suffix to Swagger Api Value. The value of this field will be added to respective service as annotation @Api by HATS toolkit.
  8. Click the Add button to add at least one method to the resource class. The Define JAX-RS RESTful Service Method wizard opens.
  9. In the HTTP Method field, from the drop-down list, select the HTTP method (GET, POST, PUT, DELETE) you want to use in combination with the URI to map to this JAX-RS resource method.
  10. Select the Use Integration Object box if you want this method to invoke an Integration Object. Clear the box if you want to generate an empty method without the Integration Object handling code. Do this to create your own customized method.
  11. If you select the Use Integration Object box, from the drop-down list, select the Integration Object you want this method to invoke.
  12. If Enable Swagger is selected in the previous step, then you can enter text in Swagger Api Operation Value field. This field will be ignored if no value is entered by you. The value of this field will be added to respective method as annotation @ApiOperation by HATS toolkit.
    Note:
    You can access HATS RESTful Swagger description document using the path /<HATScontextroot>/rest/swagger.json
  13. Click Next.
  14. If you selected the Use Integration Object box, the Choose Integration Object properties page displays. Select the input and output properties that you want exposed as parameters for the RESTful Web service. If you wish, you can provide an alias name for the property in the Alias Name field. Use the Select All, Deselect All, and Select Default buttons to help in selecting the properties.
    Notes:
    1. Defaults for single Integration Objects and EJB access beans are all macro prompts for input properties and all macro extracts for output properties.
    2. Defaults for chained Integration Objects are all macro prompts plus hPubLinkKey (which is required) for input properties and all macro extracts plus hPubLinkKey (which is required) for output properties.
    3. Defaults for chained EJB access beans are all macro prompts plus hPubLinkKey and hPubAccessHandle (both of which are required) for input properties and all macro extracts plus hPubLinkKey and hPubAccessHandle (both of which are required) for output properties.
    4. To specify that Integration Object connection overrides be exposed to the Web service, you must select the appropriate properties, for example the hPubConnectionOverrides or hPubStartPoolName properties, which are not selected by default. For more information, see Specifying Connection Overrides.
    5. For more information about the use of other Integration Object methods, see Programming with Integration Objects.
  15. Click Next.
  16. On the Configure JAX-RS Resource Method page, defaults are set that reflect the HTTP method and Integration Object you selected. For more information about these method settings and how to customize them, see Customizing RESTful service JAX-RS resource methods. For considerations when using bidirectional sessions, see Support of RESTful Web services in the HATS User's and Administrator's Guide.
  17. Click Finish.
  18. On the Configure JAX-RS Resource class page, in the Methods section, are listed the methods you have added. Use the Add button to add another method, use the Edit button to edit the selected method, and use the Remove button to remove the selected method.
  19. After you click Finish, HATS creates the JAX-RS resource file and stores it in the Source\restfulserviceclasses folder in your project.
  20. In addition, HATS adds the JAX-RS resource to the list of services for the RestServlet servlet to scan for a match. This list is maintained in the WEB-INF/wink-resources.lst file viewable in the Navigator view.
    Notes:
    1. HATS creates the WEB-INF/wink-resources.lst file when the first JAX-RS resource is created in a project.
    2. HATS updates the default WAR class loader policy of your HATS application to Single class loader for application.
    3. HATS also adds the JAX-RS facet to the project.
    4. If you create a JAX-RS resource file manually, not using the Create RESTful Service Files wizard, you must update the WEB-INF/wink-resources.lst file to map the JAX-RS resource to the RestServlet servlet.

Updating RESTful service JAX-RS resources

To update a JAX-RS resource for an Integration Object, in the HATS Projects view:

  1. Expand the Source folder and the restfulserviceclasses folder.
  2. Right-click the JAX-RS resource and select Update RESTful Service Files. The Update RESTful Service Files wizard opens.
  3. You can make changes for the JAX-RS resource by following the instructions described in Creating RESTful service JAX-RS resources.

Customizing RESTful service JAX-RS resource methods

If you want to customize a HATS RESTful service JAX-RS resource method, for example, to handle content types other than application/xml and application/json, or to define method parameters, follow these steps:

  1. Follow the instructions for Creating RESTful service JAX-RS resources or Updating RESTful service JAX-RS resources.
  2. On the Configure JAX-RS Resource class page, click Add to add a new method or click Edit to edit the highlighted method.
  3. Set the HTTP method, Integration Object, and Integration Object properties as appropriate.
  4. On the Configure JAX-RS Resource Method page, in the Method Name field, specify the Java method name.
  5. In the URI Suffix field, add any additions to the path, and add any definitions for URI parameters as PathParam parameters in the format {name}.
  6. In the Return Type field, add or change the Java type returned by this method. The default is restfulserviceclasses.JAX-RS resource class name+ _resource method name+ _Output_Properties.
  7. In the Consumes field are listed the content types (Internet media types, or MIME types) supported for input in the HTTP request body. Add or change the content types of request messages supported. Multiple content types can be specified separated with commas. HATS supports application/xml and application/json as defaults. This is only applicable for HTTP Methods POST or PUT. The HTTP GET and DELETE methods do not have HTTP request bodies and do not support the Consumes field. For these methods, input must instead be supplied as URI parameters with content type application/x-www-form-urlencoded. For more information, see Handling content.
  8. In the Produces field are listed the content types supported for output in the HTTP response body. Add or change the content types of response messages supported. Multiple content types can be specified separated with commas. HATS supports application/xml and application/json as defaults. For more information, see Handling content.
  9. In the Method Parameters fields add or change the input parameters supported by this method. Use the Add, Edit, and Remove buttons to create, modify, and delete the input parameters for this method.
  10. If you create or modify an input parameter, on the Method Parameter page complete the following fields. For more information see the JAX-RS specifications at http://jcp.org/aboutJava/communityprocess/final/jsr311/index.html.
    Parameter Type
    Select from the drop-down one of the following types as defined in the JAX-RS specification:
    • Entity - a non-annotated parameter, for example, a normal Java object, extracted from the request entity body.
    • CookieParam - parameter value is to be extracted from an HTTP cookie.
    • FormParam - parameter value is to be extracted from an HTML form parameter.
    • HeaderParam - parameter value is to be extracted from an HTTP header.
    • MatrixParam - parameter value is to be extracted from a URI matrix parameter.
    • PathParam - parameter value is to be extracted from the request URI path.
    • QueryParam - parameter value is to be extracted from a URI query parameter.
    • Context - parameter value is to be extracted from a Web application context.
    Parameter Name
    Name of the parameter. Used for CookieParam, FormParam, HeaderParam, MatrixParam, PathParam, and QueryParam.
    Default Value
    Default value if the parameter cannot be found. Used for CookieParam, FormParam, HeaderParam, MatrixParam, PathParam, and QueryParam.
    Type
    Input parameter Java type
    Name
    Input parameter name
Note:
Each JAX-RS resource must contain at least one method. If the Use Integration Object option is selected, the method contains the HATS RESTful wrapper that maps the input and output parameters for the Integration Object and invokes the Integration Object. By default, HATS maps the parameters to the Integration Object as follows: If you modify the method parameters as described in this section, HATS does not map the parameters for the Integration Object and does not perform other handling for the modified Java method. In this case, you must edit the JAX-RS resource class file and implement this yourself.

Handling content

When you create a JAX-RS resource method for an Integration Object, the Consumes field specifies the content types (Internet media types, or MIME types) the JAX-RS resource method supports as input in a HTTP request body. The Produces field lists the content types the JAX-RS resource method supports as output in a HTTP response body.

The content type of an HTTP request or response is defined in the Content-Type HTTP header field. An HTTP request can also use the Accept HTTP request header field to specify the content types it can accept in the response.

For more information, see the references below:

Content type examples

The following examples summarize handling content in HTTP requests and responses. These examples are intended to show concepts and not exact HTTP protocols.

HTTP GET and DELETE requests specify all of their input parameters on the URI using standard encoding. There is no body in such requests. The content type of the requests for these is always x-www-form-urlencoded, since that is all that is allowed for GET and DELETE requests by the HTTP protocol. The client indicates what content type it can accept in the response by supplying an Accept header.

In the GET request below, the parameter is passed as a query string on the URI. The content type acceptable in the response is specified in the Accept header field as application/xml.

GET http://www.myHost.com:9080/myApp/rest/myCustomer?name=john%20doe
Accept: application/xml

All HTTP responses carry their data in their body, no matter what kind of request prompted the response. Responses begin with header fields. The Content-Type header field in a response tells the client what type of data is contained in the body below. HTTP allows many different content types in responses, but HATS JAX-RS supports only application/xml and application/json. After the header fields and a blank line, the body begins, and contains the data in the specified format.

In the GET response below, the Content-Type header field specifies the type of data contained in the response body.

Content-Type: application/xml

<customer>
 <firstname>John</firstname>
 <lastname>Doe</lastname>
 <accountnumber>111111</accountnumber>
</customer>

By convention, a POST request typically asks to create something. The data required to fulfill the request is carried in the request body. The Content-Type indicates to the server the format of the request data. The Accept header again specifies the desired response format.

In the POST request below, the content type is specified in the Content-Type header field as application/xml and the content is supplied in the request body. The Accept header field specifies the acceptable format for data in the response, as application/json.

POST http://www.myHost.com:9080/myApp/rest/myCustomer
Content-Type: application/xml
Accept: application/json

<customer>
 <firstname>Jane</firstname>
 <lastname>Doe</lastname>
 <accountnumber>222222</accountnumber>
</customer>

In the POST response below, notice the format of the response does not have to match the format used in the request.

Content-Type: application/json

{"message":{
  "type": "resultCode",
  "value": "Jane Doe account created successfully"
}}

The HATS JAX-RS output format rule is to respond using the format specified in the Accept HTTP request header unless the client specifies a format using the URI query parameter alt as shown below: 

POST http://www.myHost.com:9080/myApp/rest/myCustomer?alt=application/xml

Customizing the response header

Sometimes you might need to customize the response header of your RESTful service. For example, to handle response headers that use Shift_JIS encoding, you must modify the REST resource class file to change the return type to javax.ws.rs.core.Response and change the content type or custom header. For example, if you want to use Shift_JIS as the default charset in a POST method with a FormParam, perform the following steps:

  1. Specify WebSphere Application Server encoding as Shift_JIS. For information about how to do this, see http://publib.boulder.ibm.com/infocenter/wasinfo/v8r0/index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/trun_svr_utf.html.
  2. Change the return type of the method in the REST resource class to javax.ws.rs.core.Response. For example, change the following code from: 
        @POST
    @Consumes({"application/x-www-form-urlencoded"})
    @Produces({"application/xml"})
    public xxx_Output_Properties invoke(@FormParam("id") String id, @FormParam("yyy") String yyy)
    {        
                        :
                        :
      return outputToClient;
    }
    To: 
        @POST
    @Consumes({"application/x-www-form-urlencoded"})
    @Produces({"application/xml"})
    public javax.ws.rs.core.Response invoke(@FormParam("id") String id, @FormParam("yyy") String yyy)
    {        
                        :
                        :
      return javax.ws.rs.core.Response.ok(outputToClient, "application/xml;charset=Shift_JIS").build();
    }

HTTP status codes

The following HTTP status codes are returned from HATS RESTful Web services:

200
Successful. No error.
400
General error. For example, incorrect content in the request body.
404
URI not found.
405
Method not allowed. For example, the service supports HTTP POST and PUT, but the URI requests HTTP DELETE.
406
Unsupported response format is requested. Supported response format is returned in the Accept header.
415
Unsupported request format. The format used for the request in invalid. Used for HTTP POST and PUT when an unsupported value is supplied in the request’s Content-Type HTTP header field.
500
Internal server error, for example an Integration Object execution error. Throws WebApplicationException.

For more information about HTTP status codes, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.

JAX-RS RESTful services considerations and limitations

Following is a list of considerations and limitations when using HATS support for JAX-RS RESTful Web services: