vRealize Automation Endpoint Configuration Service API

Endpoint Configuration Service API Specification

What Is the Endpoint Configuration Service?

You can use the endpoint configuration service REST API to create, read, update and delete endpoint types, endpoint categories, and endpoints.

Typical Use Cases

Typical use cases for the endpoint configuration service are:

• A vRA Administrator or a Solution User creates an endpoint category.
• The vRA administrator registers a new endpoint type with the endpoint configuration service.
• The IaaS administrator creates, updates or deletes an endpoint through the UI. vRA then calls the endpoint configuration service to create, update or delete endpoint information.

Key Concepts

Endpoint Category Operations

Before creating an endpoint type, an endpoint category should be registered with endpoint configuration service. Examples of endpoint categories include Virtual, Physical, IPAM, and so on. An application can call the POST /api/categories API to create endpoint categories as required.

When an endpoint category is created, the endpoint configuration service creates the endpoint category in the Postgres database.

Endpoint Type

A value that represents the type of an endpoint. A service provider creates an endpoint type within a specified category. For example, a provider of an IPAM service could create an endpoint type called "MyIPAMapp" within the IPAM endpoint category.

If a customer wants to use a new endpoint, the customer must follow a two step process:

1. Add a new endpoint type, through the endpoint configuration service.
2. Add a new endpoint instance of that endpoint type.

Endpoint Type Operations

Before creating an endpoint, the endpoint type and schema should be registered with the endpoint configuration service. When an endpoint type is created, the endpoint configuration service creates an endpoint type category in a Postgres database.

An endpoint type schema is stored only in the Postgres database. However, endpoint type information is stored in both the Postgres database and in the InterfaceTypes table on the SQL server.

How the Endpoint Configuration Service Works

When an administrator creates an endpoint instance, the UI calls the endpoint service with endpoint data. The endpoint service performs the following steps:

• Validates the data against the schema.
• Gets the IaaS repository endpoint from the component registry.
• Saves the new endpoint data to the Postgres database.
• Calls the repository service to save the data.
• Returns SUCCESS to the endpoint UI.

The logic for update and delete is same as for create.

User Roles and Permissions

Different user roles have different permissions for working with endpoints.

Endpoint Type Operations and Endpoint Type Categories

The following user roles have permission for the following:

• GET - IaaS Administrators, vRA Administrators, Solution Users.

• PUT/POST/DELETE - vRA Administrators, Solution Users.

Endpoint Operations

• GET (global endpoint, without secure data) - IaaS Administrators, Solution Users.
• GET (any endpoint, secure data) - Solution Users.
• PUT/POST/DELETE - Solution Users.
• PUT/POST/DELETE - IaaS Administrators, Solution Users.

Handling Credentials

In vRA 7.0, credential information is stored separately from the management endpoint information. So, when creating an infrastructure endpoint, the customer must specify the credential information separately, making endpoint creation a two-step process. With the vRA 7.1 endpoint configuration service, the endpoint information is specified along with the credential information. The UI displays all the information in a single place, and the endpoint data is stored together at a single place as well.

Password information must be encrypted when saved to the database. To specify that a field needs to be encrypted, the corresponding field must be marked as securestring in the database schema. When saving endpoint information, the endpoint service goes through all the fields of type securestring and encrypts the field data, before saving it to the database. This ensures that passwords are not saved as plain text in the database.

When retrieving endpoint information from the endpoint service, by default, all the fields that use securestring are set to empty. Only specific APIs return fields marked with securestring. Only solution users can retrieve secure fields.

Creating New Endpoint Types

To consume a new endpoint that belongs to a new endpoint type, a service provider must:

1. Add a new endpoint type, through the endpoint configuration service.
2. Add a new endpoint instance of that endpoint type.

For step 1, the customer (service provider) must also define a new schema for the endpoint type. The schema should indicate all the permissible fields and their corresponding values for the endpoint type. The endpoint object used for creating the endpoint should confirm to the schema of the endpoint type that the endpoint belongs to.

Additional Information

For more detailed information on using the the API, refer to the vRA Programming Guide.