Retaining Version 5 vanity endpoint behavior in a Catalog

The behavior of vanity endpoints in a Catalog has changed in API Connect Version 10 compared with Version 5. However, you can modify your Catalog settings to retain the Version 5 behavior.

About this task

A vanity endpoint represents the endpoint by which an API is known externally; that is, the endpoint that is published to the Developer Portal and is used by an application developer to invoke the API.

You can modify your Catalog settings to define vanity endpoints that retain the API Connect Version 5 behavior.

You can modify the Catalog settings in either of the following ways:

Use the API Manager user interface.
Use the developer toolkit CLI.

You can also use the API Connect REST APIs; see the API Connect REST API documentation.

Procedure

To modify the Catalog settings to retain Version 5 vanity endpoint behavior by using the API Manager user interface, complete the following steps:
1. Click API Endpoints in the Catalog settings navigation pane. The Vanity API Endpoint page opens.
2. Click Edit, then select v5 legacy behavior.
3. To use the API Connect URLs, select Use gateway URLs. To configure a vanity endpoint, select Display vanity endpoint then provide the following information:
  - Endpoint: The URL of your vanity endpoint.
  - Gateway Uri: The URL of the gateway service that is enabled in the Catalog and is associated with the vanity endpoint; select from the list provided.
  - Summary: An optional description of the vanity endpoint.
To modify the Catalog settings to retain Version 5 vanity endpoint behavior by using the developer toolkit CLI, complete the following steps:
1. Log in to your API Connect Management server as a member of a provider organization, by using the following command:
```
apic login --server mgmt_endpoint_url --username user_id --password password --realm provider/identity_provider
```
  where:
  - mgmt_endpoint_url is the platform API endpoint URL.
  - user_id is the user ID that you want to log in with. The user ID must be a member of a provider organization. This is an ID that you could also use to log in to the API Manager user interface.
  - password is the password associated with the supplied user ID.
  - identity_provider is the identity provider that is used to authenticate the supplied user ID.
  For example:
```
apic login --server platform-api.myserver.com --username myuser --password mypassword --realm provider/myldap
```
  You can determine which identity provider to use in the --realm parameter by entering the following command to see a list of all available identity providers (you do not need to be logged in to use this command):
```
apic identity-providers:list --scope provider --server platform_api_host_name --fields title,realm
```
  For example,
```
apic identity-providers:list --scope provider --server platform_api_host_name --fields title,realm 
total_results: 2
results:
  - title: API Manager User Registry
    realm: provider/default-idp-2
  - title: Corporate LDAP user registry
    realm: provider/corporate-ldap
```
  The title value should enable you to determine which identity provider to use; you can then copy the corresponding --realm parameter directly from the displayed realm value. For any identity providers that were created by your administrator after API Connect was installed, the names will have been determined at creation time. The default API Manager Local User Registry for login as a member of a provider organization is default-idp-2.
  For full details on how to log in to your management server from the CLI, see Logging in to the management server.
2. Define the configuration for your vanity endpoint by creating a YAML file with the following structure:
```
legacy_endpoint_behavior: enabled
v5_endpoint_substitution_behavior:
  base_endpoints:
    - endpoint: vanity_endpoint_url
      description: description
      gateway_service_url: gateway_service_url
  unenforced_api_base_endpoint: unenforced_api_base_endpoint
```
  where:
  - the legacy_endpoint_behavior: enabled setting specifies that the Catalog retains API Connect Version 5 behavior. A Catalog can support either Version 5 behavior or Version 10 behavior but not both.
  - vanity_endpoint_url is the URL of your vanity endpoint.
    Note: API Connect Version 5 supports only the host name in a vanity endpoint URL; a URL of the form https://host_name/path is not supported. Therefore the vanity endpoint URL that you supply here must contain only a host name; for example, https://vanity.com.
  - description (optional) is a description of your vanity endpoint.
  - gateway_service_url is the URL of the gateway service that is enabled in the Catalog and is associated with the vanity endpoint.
    Note: You can determine the gateway service URL by using the following command:
    
    apic configured-gateway-services:list --scope catalog --catalog catalog_name --server mgmt_endpoint_url --org organization_name
    
    where:
    
    gateway_service_name is the name of the gateway service.
    
    catalog_name is the name of the Catalog.
    
    organization_name is the name of the provider organization that contains the Catalog.
    
    The command output lists all the gateway services that are enabled in the Catalog, together with their gateway service URLs.
  - unenforced_api_base_endpoint (optional) is a custom API URL that specifies the URL for APIs that are deployed to a third party gateway.
  Note: base_endpoints: is an array. You can configure multiple vanity endpoints by defining multiple endpoint: entries.
3. Modify your Catalog settings by using the following command:
```
apic catalog-settings:update --server mgmt_endpoint_url --catalog catalog_name --org organization_name filename
```
  where filename is the name of the YAML file that you created in step 2.
4. Confirm your updated Catalog settings by using the following command:
```
apic catalog-settings:get --server mgmt_endpoint_url --catalog catalog_name --org organization_name --output -
```