Working With the REST BC WSDL Document
The WSDL document defines a REST interface for the project. You create and
configure the WSDL document using the New WSDL Wizard, and you can further
configure the interface using the WSDL Editor in NetBeans.
The following topics provides instructions for working with the WSDL document for REST:
Creating the REST BC WSDL Document
The following topics provide instructions for creating an inbound and outbound REST WSDL
document, and also provide reference information for the fields on the New WSDL
Wizard.
To Create a WSDL Document for REST Inbound
- In the NetBeans Projects window, right-click the project or a folder within the
project where you want to add the WSDL document.
- Point to New and then select WSDL Document.
The New WSDL Document Wizard appears.
- Enter a name for the WSDL document, and verify or update the folder
location for the file.
- Select Concrete WSDL Document.
The Binding and Type fields appear.
- For the Binding, select REST; for the Type, select REST – Inbound.
- Click Next.
The Operation Detail window appears with the Get tab displayed.
- To add a GET operation, do the following:
- On the Get tab, click Add Operation.
New fields appear on the wizard.
- Enter a name for the operation, and click the Browse buttons to select
the request and response message types.
- Click Edit Operation.
The Edit Operation Properties window appears.
- Enter values for the fields described in Table 1.
- To add PUT, POST, DELETE, and HEAD operations, repeat the above steps from
the appropriate tab on the wizard.
- On the New WSDL Document Wizard, click Finish.
To Create a WSDL Document for REST Outbound
- In the NetBeans Projects window, right-click the project or a folder within the
project where you want to add the WSDL document.
- Point to New and then select WSDL Document.
The New WSDL Document Wizard appears.
- Enter a name for the WSDL document, and verify or update the folder
location for the file.
- Select Concrete WSDL Document.
The Binding and Type fields appear.
- For the Binding, select REST; for the Type, select REST – Outbound.
- Click Next.
The Operation Detail window appears with the Get tab displayed.
- To add a GET operation, do the following:
- On the Get tab, click Add Operation.
New fields appear on the wizard.
- Enter a name for the operation, and click the Browse buttons to select
the request and response message types.
- Click Edit Operation.
The Edit Operation Properties window appears.
- Enter values for the fields described in Table 2.
- To add PUT, POST, DELETE, and HEAD operations, repeat the above steps from
the appropriate tab on the wizard.
- On the New WSDL Document Wizard, click Finish.
New WSDL Wizard Properties for REST
The following tables list and describe the inbound and outbound operation properties for
the REST BC. These properties are accessed from the Operation Details page of
the New WSDL Wizard.
Table 1 Edit Operation Properties (Inbound)
|
|
Path |
The path to the operation resource. This property is
required. |
HTTP Listener |
The name of the HTTP listener to bind to. The default
value is Default HTTP Listener. This property is optional. |
Consume Types |
The acceptable MIME types for the request
payload, specified in JSON format. Enter the types in square brackets with each
type contained in double-quotes. Separate multiple values by a comma. For example: [ "text/plain", "application/xml" ] This property is
optional. |
Produce Types |
The acceptable MIME types for the response payload, specified in JSON format
as above. This property is optional. |
Forward as Attachment |
An indicator of whether to
forward the payload as an attachment. Select the check box to have the
payload forwarded as an attachment. This property is optional. |
User Defined |
A list of
user-defined properties in java.util.Properties format (key and value pairs). For example: serverName=test This property
is optional. |
|
Table 2 Edit Operation Properties (Outbound)
|
|
URL |
The URL to the external resource. This property is required. |
Accept Types |
The
acceptable media types for the response, specified in JSON format. Enter the types
in square brackets with each type contained in double-quotes. Separate multiple values by
a comma. For example: [ "application/json" ] This property is optional. |
Accept Languages |
The preferred natural languages for
the response, specified in JSON format. This property is optional. |
Content Types |
The content type of
the outbound payload. If no value is specified, this defaults to any type. This
property is optional. |
Headers |
Custom HTTP headers for the outbound payload. Enter the headers in
curly brackets as name value pairs with the name and value each in
double-quotes and separated by a space, a colon, and another space. Separate multiple
name value pairs by a comma. For example: { "host" : "MyServer.com", "Content-Subtype" : "application/json/customers"} Custom headers are optional. |
Param Style |
A
style for the URI parameters. Select one of the following options:
Query – Name and value pairs that specify attributes of the full URI (external resource). Query parameters are delimited by an ampersand (&) and are separated from the rest of the URI by a question mark (?).
Matrix – Name and value pairs that specify attributes of one segment in a URI. Matrix parameters can occur after the segment in the URI that they modify. Matrix parameters are delimited by a semicolon (;) and are also separated from the segment they modify by a semicolon.
|
Params |
Custom HTTP parameters
for the URI. Enter the parameters in curly brackets as name value pairs
with the name and value each in double-quotes and separated by a space,
a colon, and another space. Separate multiple name value pairs by a comma.
For example: { "status" : "Active", "billing" : "Current"} Custom parameters are optional. |
Basic Auth User Name |
The login ID of the
user for authentication. If the property is populated, a basic authentication header is
added to the HTTP request. |
Basic Auth Password |
The login password corresponding with the
above user name. |
User Defined |
A list of user-defined properties in java.util.Properties format (key
and value pairs). For example: serverName=test This property is optional. |
|
Configuring REST BC WSDL Attributes
Once you create the REST BC WSDL document, you can add and
update the WSDL attributes that are specific to the REST configuration. The REST BC
includes both service-level WSDL elements and binding-level WSDL elements, but some of these
elements are placeholders only.
To Configure REST BC WSDL Attributes
- In the NetBeans IDE, double-click the WSDL document you want to configure.
The document appears in the WSDL Editor in WSDL view.
- Click Source.
The view changes to display the source code.
Note - Operation properties cannot be configured in WSDL view.
- Scroll to the binding element, and modify any of the operation attributes described
in REST Operation Element.
- When you are finished, save and close the file.
Service Level REST WSDL Element
The service-level REST element is rest:address. This is a placeholder element only, and
does not need to be configured. When you create a WSDL file in
the NetBeans IDE, the New WSDL Wizard generates the empty rest:address element.
The following example illustrates the REST WSDL service element:
<service name="RestOutboundService">
<port name="RestOutboundWSDL_OutboundPort" binding="tns:RestOutboundBinding">
<rest:address/>
</port>
</service>
Binding Level REST WSDL Elements
Binding level WSDL elements allow you to define and configure the REST operation
performed against the external resource along with information about the resource. The REST
Binding Component binding level WSDL elements include the rest:binding and rest:operation extensibility elements,
but the rest:binding element is a placeholder.
REST Binding Element
The REST binding extensibility element specifies that the WSDL document is configured for
the REST protocol. This is a placeholder element only, and does not need
to be configured. When you create a WSDL file in the NetBeans IDE,
the New WSDL Wizard generates a binding element, which includes a name you
specify and a type that is generated by the wizard, and also includes
the empty rest:bindingelement.
The following example illustrates the REST binding element:
<binding name="RestOutboundBinding" type="tns:RestOutboundPortType">
<rest:binding/>
...
REST Operation Element
The REST operation element includes attributes that define the supported operations, along with
payload types, URL information, and HTTP authorization. The REST Binding Component supports the
GET, PUT, POST, DELETE, and HEAD operations. These attributes correspond to the properties you
can configure from the Edit Operation Properties on the New WSDL Wizard.
When you create a WSDL file in the NetBeans IDE, the New
WSDL Wizard generates a rest:operation element in the binding element, and includes any attribute configurations
you entered for the operation properties on the wizard.
Table 3 REST BC Inbound WSDL Attributes
|
|
http-listener-name |
The name of the
HTTP listener to bind to. The default value is Default HTTP Listener. This property is optional. |
path |
The
path to the operation resource. This property is required. |
method |
The HTTP operation to
access the resource specified above. This attribute default to GET. Enter any of
the following operations:
For more information, see Supported HTTP Methods. |
consume-types |
The acceptable MIME types for the
request payload, specified in JSON format. Enter the types in square brackets with
each type contained in double-quotes. Separate multiple values by a comma. For example: [ "text/plain", "application/xml" ] This property
is optional. |
produce-types |
The acceptable MIME types for the response payload, specified in JSON format
as above. This property is optional. |
forward-as-attachment |
An indicator of whether to forward the
payload as an attachment. Select the check box to have the payload forwarded.
This property is optional. |
user_defined |
A list of user-defined properties in java.util.Properties format (key and
value pairs). For example: serverName=test This property is optional. |
|
Table 4 REST BC Outbound WSDL Attributes
|
|
url |
The URL to the external resource.
This property is required. |
method |
The HTTP operation to access the resource specified above.
This attribute default to GET. Enter any of the following operations:
For more information,
see Supported HTTP Methods. |
accept-types |
The acceptable media types for the response, specified in JSON format. Enter
the types in square brackets with each type contained in double-quotes. Separate multiple
values by a comma. For example: [ "application/json", "text/plain" ] This property is optional. |
accept-languages |
The preferred natural languages
for the response, specified in JSON format. This property is optional. |
content-type |
The content type of
the outbound payload. If no value is specified, this defaults to any type. This
property is optional. |
headers |
Custom HTTP headers for the outbound payload. Enter the headers in
curly brackets as name value pairs with the name and value each in
double-quotes and separated by a space, a colon, and another space. Separate multiple
name value pairs by a comma. For example: { "host" : "MyServer.com", "Content-Subtype" : "application/json/customers"} Custom headers are optional. |
param-style |
A style
for the URI parameters. Select one of the following options:
Query – Name and value pairs that specify attributes of the full URI (external resource). Query parameters are delimited by an ampersand (&) and are separated from the rest of the URI by a question mark (?).
Matrix – Name and value pairs that specify attributes of one segment in a URI. Matrix parameters can occur after the segment in the URI that they modify. Matrix parameters are delimited by a semicolon (;) and are also separated from the segment they modify by a semicolon.
|
params |
Custom HTTP parameters for
the URI. Enter the parameters in curly brackets as name value pairs with
the name and value each in double-quotes and separated by a space, a
colon, and another space. Separate multiple name value pairs by a comma. For
example: { "status" : "Active", "billing" : "Current"} Custom parameters are optional. |
basic-auth-username |
The login ID of the user for authentication. If
the property is populated, a basic authentication header is added to the HTTP
request. |
basic-auth-password |
The login password corresponding with the above user name. |
user_defined |
A list of user-defined
properties in java.util.Properties format (key and value pairs). For example: serverName=test This property is
optional. |
|
The following example illustrates the REST operation element:
<binding name="RestOutboundBinding" type="tns:RestOutboundPortType">
<rest:binding/>
<operation>
<rest:operation>
<![CDATA[
url=http://{bucket}.s3.amazonaws.com/{resource}
method=GET
accept-types=[ "text/plain" ]
accept-languages=[ ]
content-type=
headers={ }
param-style=Query
params={ "status" : "Active", "billing" : "Current" }
basic-auth-username=gsmythe
basic-auth-password=1qazMKO)
]]>
</rest:operation>
...
</operation>
</binding>