Hybrid Integration 10.2 | Integrating On-Premises Applications | Document Conventions | Working with REST API Descriptors | Creating a REST API Descriptor from a REST Resources
 
Creating a REST API Descriptor from a REST Resources
When you create a REST API descriptor, you select the REST resources that you want to include. You can also specify the MIME types that can be consumed and produced by the operations in the REST API descriptor, the supported protocols, and the base path for the REST API descriptor.
Keep the following in mind when creating a REST API descriptor:
*A REST resource must already exist on Integration Server.
*A REST API descriptor can include either REST resources created using the legacy approach or resources created using the URL template-based approach. The descriptor cannot include a combination of REST resources created using both the approaches.
*A REST API descriptor does not support duplicate variable names in the input parameters or output parameters. The REST API descriptor uses only the first variable with a particular name and ignores subsequent identically named variables. For example, if the input parameters include a String variable and a String List variable named “myField, the REST API descriptor uses only the first occurring “myField” in the REST definitions. However, if the output parameters also include a String variable named “myField”, the REST API descriptor includes the output “myField” in the REST definitions.
*A REST API descriptor created from REST resources using the legacy approach can include a resource with a _default service. However, Integration Server does not create an operation that corresponds to the _default service.
*The names of documents and document references in a REST API descriptor must be unique. That is, a REST API descriptor does not support identically named documents and document references. If you create a REST API descriptor that contains more than one document or document reference with the same name, the generated Swagger document contains only one definition that corresponds to that document name.
* To create a REST API descriptor
1. In the Service Development perspective of Designer, select File > New > REST API Descriptor.
2. In the Create a New REST API Descriptor dialog box, select the folder in which you want to save the REST API descriptor.
3. In the Element name field, type a name for the REST API descriptor using any combination of letters, numbers, and the underscore character. For more information about restricted characters, see Guidelines for Naming Elements.
4. Click Next.
5. Depending on the type of REST resources you want to include in the REST API descriptor, select either REST V2 Resources (Recommended) or REST Resources.
Note: If you want to create a REST API descriptor from a Swagger document, see Creating a REST API Descriptor from a Swagger Document.
6. In the Specify REST API Descriptor General Details panel, provide the following information:
In this field...
Specify...
Title
A title for the application represented by the REST API descriptor.
Description
A description of the application represented by the REST API descriptor.
Application Version
A version number for the application. The default is 1.0.
Note: The Application Version is not the version of the Swagger specification.
Host:Port Name
The host and port for the Integration Server on which the application resides in the format: host:port
By default, the REST API descriptor uses the primary host:port of the Integration Server to which Designer is connected.
Path
The base path for the REST API descriptor. The path must begin with a “/” (slash).
For REST resources using the legacy approach, Integration Server obtains this value from the watt.server.RESTDirective server configuration parameter and the default path is /rest.
For REST resources using the URL template-based approach, the default value of path is /rad/<namespace name of REST API descriptor>
Consumes
Select the MIME types that operations in the REST API descriptor can consume.
The MIME types you select here apply to all the operations in the REST API descriptor. However, you can override the MIME types on a per operation basis. For more information, see Changing the MIME Types for an Operation in a REST Resource.
If you do not see the MIME type you want to use listed, you can update the list of available MIME types. For more information, see Changing the Available MIME Types for a REST API Descriptor.
Produces
Select the MIME types that operations in the REST API descriptor can produce.
The MIME types you select here apply to all the operations in the REST API descriptor. However, you can override the MIME types on a per operation basis. For more information, see Changing the MIME Types for an Operation in a REST Resource.
If you do not see the MIME type you want to use listed, you can update the list of available MIME types. For more information, see Changing the Available MIME Types for a REST API Descriptor.
7. Click Next.
8. In the Select the REST Resources panel, select one or more REST resources to include in the REST API descriptor.
9. Click Finish.
Designer creates the REST API descriptor using the information you provided along with the selected REST resources.
Copyright © 2015- 2018 | Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors.
Innovation Release