Create a Service Connection from a Service Specification

You create a connection from a service specification when you know the URL of the OpenAPI/Swagger or Oracle ADF Describe file that describes the service. You can also upload the specification file from your local system.

To create a connection from a service specification:

1. Click Services in the Navigator.
2. In the Services pane, click the + sign and select Service Connection.
3. Click Define by Specification in the Select Source step of the Create Service Connection wizard:
   
   

   
   Description of the illustration service-connections-create-byspecification.png

   
   
4. Enter a name for the connection in the Service Name field.
   
   

   
   Description of the illustration create-svc-conn-full-page-name-visapp.bmp

   
   The name you specify will be the connection's display name in your application.
5. Select the API Type for the service you want to connect to:
   • Select OpenAPI / Swagger if you have an OpenAPI/Swagger specification for your service.
   • Select ADF Describe for any REST API that has an ADF Describe file, including Oracle Cloud Applications REST API.
   • Select ADF Describe (cache-enabled) if you need to create a service connection to an Oracle Cloud Applications REST API that has a Describe URL.
6. Select the location of the Service Specification document.
   • If you're creating a service connection to an Oracle Cloud Applications REST API (for example, CRM, FSCM, HCM), select Web address, click the URL text box and select the appropriate backend to fill in the service description's URL.
     Then type in the rest of the Describe URL to the resource using this format:

     <backend URL path>/<REST-API-version>/<resource-name>/describe

     For example, for the HCM absences resource, you'd add /11.13.08.05/absences/describe to the selected HCM URL in the text box, where 11.13.18.05 is the REST API version.

     To ensure that the metadata is cached efficiently, specify the actual REST API version (for example, 11.13.18.05) instead of using “latest” for the version. To figure out the latest REST API version, consult the product's Oracle Cloud Applications REST API documentation.

     Tip:

     To specify multiple resources (for example, both contracts and expenses), you'll need to use a slightly different URL. Use this format if you're specifying the contracts and expenses resources:

     <backend URL path>/<REST-API-version>/describe?resources=contracts,expenses

   • If you have an external URL representing the service specification (for example, an OpenAPI3 URL), select Web address and enter the service descriptor's URL in the URL field.

     If you're using an IP address instead of a proper DNS-based URL in a production environment, you're probably using self-signed certificates. Certificates based on IP addresses are less secure and more difficult to maintain than DNS-based ones. To avoid potential security issues, self-signed certificates should never be used in production environments. An audit warning will be displayed whenever you use an IP address-based service connection.

   • If you have a document that contains the service specification, select Document, then either drag and drop the file that describes the service from your local system to the dialog or use the file browser to locate and select it on your system.

   Note:

   If the service specification URL does not match an existing backend, you will need to create a new backend. Instructions for creating a new backend from a service specification URL are covered in a later step.
7. Select a Metadata Retrieval Option.
   

   If you entered a web address, you can select Dynamically retrieve metadata to create a dynamic service connection that always pulls in the most up-to-date service definition for your application or you can select Copy full OpenAPI to the application to copy the complete service metadata during development and statically store it in your visual application's sources.

   If your API type is ADF Describe, you may want to select Copy minimal OpenAPI to the application (recommended) to copy the minimal metadata for the endpoints you'll select in the next step and dynamically retrieve the request/response schema, when required.

8. If you did not have a backend to match your service specification URL, add service connection details as needed, then create a backend:
   1. Update the Security and Connection Type settings as needed.
   2. Click Create Backend.
   3. In Backend URL, use the slider to specify which part of the URL you want to use for the backend.
      
      
      Description of the illustration create-svc-conn-add-backend.bmp
      
      
   4. Add a name and optional description for the backend.
   5. Update the Security and Connection Type settings for the backend as needed.
9. Do one of the following:
   • If you have an ADF Describe API type, continue to the next step.
   • If you have an OpenAPI/Swagger API type, click Create. The procedure is complete.
10. Click Next and select the resources and endpoints you want to add.
    The Select Endpoints pane displays a list of the endpoints and child objects available for each resource provided by the service.
    1. Select a top-level object to select all endpoints for that object or expand the top-level object node and select individual endpoints to improve performance.
       
    2. Click Create.

After creating a service connection, you can select it in the Navigator to open the connection in the editor and edit the endpoints associated with the service and other connection details.

You can also test the service connection like this:

1. From the Endpoints tab, select one of the resource's methods to test.
2. Go to the Test tab and, under Response, enter an integer for a query parameter.
3. Click Send Request.
4. Check the Send Request status. A status of 200 indicates success.