Create a Service Connection from an Endpoint

You can create a connection from an endpoint when you know the base URI of a service and can provide the necessary parameters for connecting to the service, such as authentication details and an example of the Response body.

To create a service connection from an endpoint's URL:

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

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

   
   
4. Select the HTTP method and enter the endpoint URL.

   Note:

   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. You need to be aware that certificates based on IP addresses are less secure and more difficult to maintain than DNS-based ones and, 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 know the result expected from the endpoint URL, select it in the Action Hint drop-down list to indicate what the endpoint does. For example, when you select GET as the Method, select Get One as the Action Hint if the endpoint URL will retrieve a single record, or Get Many if the endpoint will retrieve multiple records. If the endpoint URL will create a record, you would select POST as the method and Create as the Action Hint.
   Description of the illustration service-connections-create-specifyendpoint.bmp

   If an existing backend match is found, the URL will fill the field automatically; otherwise, you will need to create a new backend. See the following step for more details.

   When you're done, click Next.

5. If you did not have a backend to match your service specification URL, click Create Backend.
   1. In Backend URL, use the slider to specify which part of the URL you want to use for the backend.
      
      
      Description of the illustration service-connections-create-backend.bmp
      
      
   2. Add a name and optional description for the backend.
   3. (Optional) Change the Security and Connection Type settings for the backend.
   4. Click Next.
6. In the Overview tab, add a Service name, and confirm the title and version. Optionally, enter a description.
7. If you want the service connection to only be used by the server (for example, from a Groovy script), select Server Only Connection.
8. Click the Server tab. If you selected a pre-existing backend in Step 4, all the details here will be read-only. If you created a new backend, complete the following details:
   • Specify an application profile if you want to use the server that is specified here for a specific phase of an application’s development.
   • Add any static headers (custom and secure) to be used when the service connection connects to the REST service using this server.
   • If your service requires authentication, select an authentication option for logged-in users.

     Authentication is None by default.

   • Choose a connection type, set by default to Dynamic, the service supports CORS.
9. Click the Operation tab to view the Endpoint ID that Visual Builder will use to identify the REST API endpoint you specified at the start of this task.
10. Click the Request tab to add headers and URL parameters to the request.

    Depending on the endpoint, you might want to add custom headers or path or query parameters that are passed as part of the request.

    
11. Click the Response tab and enter the response body for the endpoint.

    The Response tab displays the media type's OpenAPI3 metadata artifacts that can be represented: the example and the schema. You paste in an example of the body of the response into the text area and then click the Save Example button to commit your input or click the Reset button to clear it and start over. These buttons will stay disabled until you add or edit the example text.
    
    Description of the illustration vb-response-example.png
    

    After you click the Save Example button, your new example content is saved, the schema is generated, and the Type Structure panel displays.

    If you don't have an example to add, you can use the Test tab to send a request to the service, then save and use the response that is returned as your example (or edit it as needed) in the tab's text area.

    Note:

    The panels you see in the Response tab are determined by the presence or absence of the example and the schema:

    • If neither the schema nor the example exist, such as when you're creating a new service by using the Define by Endpoint flow in the wizard, the tab displays just the Example text area.
    • If you arrive at a tab for an existing service whose endpoint already has the schema and example defined, the Type Structure panel and the Example text area are both displayed.
    • You may also encounter cases where existing endpoints have a schema defined, but there is no example. In most of these cases, it's either undesirable or potentially detrimental to include the Example text field on the page, so a placeholder panel with a boilerplate message that says there is no example is displayed instead.
12. Click the Test tab to test your request (based on the settings in the other tabs) and view the response from the endpoint.

    Click Send Request to view the Response body and headers and confirm that the data you receive is what you're expecting.

    

    You can experiment with different request parameters until you achieve the response you want. If your response returns an error, check the details of your connection, for example, ensure that you're using the correct credentials or that the service uses a valid SSL certificate.

13. Click Create when you are satisfied with the parameters of your request and the response.

Tip:

After you add an endpoint from the service, you can add more endpoints from the same service by clicking + Endpoints in the Endpoints tab of the connection. For example, defining a Get Many endpoint is enough if you only want to view records, but you'll need to create more endpoints to create, edit, or delete records.