DevOps Edition for Continuous Integration 10.5 | Service Development Help | Working with REST API Descriptors | About Provider REST API Descriptors | Creating a Provider REST API Descriptor from a REST Resource
 
Creating a Provider REST API Descriptor from a REST Resource
When you create a provider REST API descriptor (RAD), 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 RAD, the supported protocols, and the base path for the RAD.
Keep the following in mind when creating a RAD:
*A REST resource must already exist on Integration Server.
*A RAD 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 RAD does not support duplicate variable names in the input parameters or output parameters. The RAD 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 RAD uses only the first occurring “myField” in the REST definitions. However, if the output parameters also include a String variable named “myField”, the RAD includes the output “myField” in the REST definitions.
*A RAD 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 RAD must be unique. That is, a RAD does not support identically named documents and document references. If you create a RAD 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 RAD.
3. In the Element name field, type a name for the RAD 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. In the Select the Source Type dialog box, select Provider.
6. Select Existing REST Resource(s) as the RAD source.
Depending on the type of REST resources you want to include in the RAD, select either REST V2 Resources (Recommended) or REST Resources (Deprecated). Click Next.
*Software AG recommends that you use the REST V2 version as the legacy REST usage is deprecated.
*If you want to create a RAD from a Swagger document, see Creating a Provider REST API Descriptor from a Swagger Document.
7. 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 RAD.
Description
A description of the application represented by the RAD.
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 RAD uses the primary host:port of the Integration Server to which Designer is connected.
Base Path
The base path for the RAD. 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 RAD can consume.
The MIME types you select here apply to all the operations in the RAD. However, you can override the MIME types on a per operation basis. For more information, see Modifying Tags for Operations 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 RAD can produce.
The MIME types you select here apply to all the operations in the RAD. However, you can override the MIME types on a per operation basis. For more information, see Modifying Tags for Operations 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.
8. Click Next.
9. In the Select the REST Resources panel, select one or more REST resources to include in the RAD.
10. Click Finish.
Designer creates the RAD using the information you provided along with the selected REST resources.
Copyright © 2017-2019 | 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.