In this article

Overview

You can make your APIs accessible to users outside of the SnapLogic ecosystem in the API Portal. The API Management > Portal Manager enables you to publish, unpublish, deprecate, and retire versions of your API when published first from API Management > API Manager. As an Org Admin, you can create a Developer Portal for your API developers to publish their APIs. The API Management > Portal Manager is the administrative console where you can manage the lifecycle of your APIs. The Developer Portal is the public-facing page that consumers use to explore those APIs.

You can perform the following actions in the Portal Manager:

• View APIs published on the Developer Portal. The API is available as read-only with documentation included for the interested consumer.

• Unpublish an API version from the portal to update any of its components. The API is removed from the Developer Portal, but can be published again on the API’s Version Details page.

• Deprecate an API version to notify users that this version of the API is obsolete. The API is marked Deprecated in the Developer Portal and Portal Manager. A deprecated API can still be updated and published again, but once it is marked deprecated, the API version status cannot change to any other but Retired.

• Retire an API version from the Developer Portal. The API is removed from the Developer Portal and Portal Manager and can no longer be updated or published. Tasks are disabled and assets become read-only in the UI.

The following video demonstrates these workflows:

Publishing an API Version or a Proxy to the Developer Portal

Publishing an API version and publishing a Proxy follow the same workflow.

1. In the API Manager, go to the APIs & Proxies tab.

2. Navigate to the Details page of the item you want to publish.

   • For API versions,

     • Click the API’s name in the list.

     • Go to the Versions tab.

     • Click the version number.

   • For Proxies, click the proxy’s name in the list.

3. In the Version Details tab or Proxy Details tab, click Publish.

   

4. In the first Publish API dialog, configure the following settings:

   

   • Upload API Documentation: Both JSON and YAML file specifications are supported.
     Choose one of the following options:

     • File from URL. References a file in the specified URL.

     • File from Version. Selects a file asset included in the API Version.

     • Local File. Uploads a file from your local machine.

     • . Choose the specification file from the dropdown list.

   • Contact Email: The email address that an API consumer can contact about the API Version or Proxy. This field automatically displays the SnapLogic username of the user publishing the API, which you can change to any valid email address.

   • Contact Slack: Slack channels and recipients (with the appropriate Slack URL) that an API consumer can contact about the API Version or Proxy.

   • Portal Categories: Select from the list of categories that are preconfigured for your Developer Portal.

   • Server: Select the Snaplex to host the API. API Proxies do not support this option.

   • Mark as Featured API: Showcase this API Version or Proxy in the Featured section of the Developer Portal.

   • Dev Portal: select one of the following two options.

     • External - Public: (default option) Makes the API visible to all Developer Portal users.

     • Internal - Private: Makes the API visible only to APIM users.

5. In the second Publish API dialog, configure the following settings:

   

   • Under Subscription Settings:

     • Allow Subscriptions: If selected, API consumers can subscribe to this API Version or Proxy.

     • Auto Approve Keys: If selected, subscriptions are automatically approved.

   • Under Key Settings:

     • Custom Header: Specify the name of the custom header that will hold the subscribed application’s client key, when sending a request to call the API.

     • Query Parameter: Specify the name of the query parameter that will hold the subscribed application’s client key, when sending a request to call the API.
       IMPORTANT: If you modify these settings for an already published API, the subscriber receives an automatically generated email notification.
       NOTE: If neither field value is specified:

       • If API is published with OAS 3.0 the API consumer must pass the secret key in the header as an Authorization key only.

       • If API is published with OAS 2.0 the API consumer must pass the secret key in the header as an Authorization key with the prefix Bearer.

6. Click Publish and Exit.

In the Portal Manager, the APIs tab displays all published API Versions and Proxies.

• The name of a published API is followed by the published version number.

• The name of a published Proxy is the name of the API from the API specification, not the name of the Proxy as shown in the API Manager. It is not followed by a version number.

In the Developer Portal, Proxies are indistinguishable from APIs. The Proxy’s version number is derived from the API specification used.

To confirm the publication of your API, you can navigate to the target Version and view its Publication status. You can also view the publication status on the API Management > Portal Manager page.

Edit API Specifications

1. From the Publish API dialog, click the icon next to your selected file to open the API Specifications Editor.

   

2. You can edit your API specifications (both JSON and YAML files) and view any errors with the code. When you are done making changes, click Save to close this window. 

   

Add Documentation References to your Published API

You can add a documentation reference to your APIs or Proxies on the Developer Portal. When publishing an API version or Proxy, you can include a documentation link.

1. In the Version Details tab or Proxy Details tab, do the following:

   1. Click Generate API Specification and choose the YAML as the file type. The YAML format is more readable. You can select either OAS 2.0 or 3.0 version.

   2. Click Publish to open the Publish API dialog.

2. Select File from Version, and choose your generated specification file.

   

3. Click to open the Swagger Editor. The API Editor opens in another browser tab.

In the specification, add the following fields under the version field, as shown in the following image:

• externalDoc

  • Description: Enter a description.

  • url: Add a valid URL to the API documentation

• "termsOfService": Add a valid URL to the API's service agreement

• "license"
      "name": Enter the name of the license
        "url": Add the URL for the license agreement

• On the top right, click Save. The Swagger Editor closes.

• Return to the Publish API dialog in the tab from which you started.

• Complete the remaining fields in the Publish API dialog, and then click Publish.

• Go to the target API in the Developer Portal, and verify that the doc link works.

  

Unpublishing an API Version from the Developer Portal

When you unpublish an API version, that API is removed from the Developer Portal but remains in the Portal Manager.

1. In the API Management console, perform one of the following actions:

   • In API Manager, navigate to the target API version, then click Unpublish.

     

   • Click Portal Manager, scroll to the target API, and in the Actions column, click Unpublish.

     

2. Review the Unpublish API confirmation prompt, then click Unpublish.

   

To verify that the API version is unpublished, check the status in the Portal Manager or Version Details of the API version.

Republish an API Version or Proxy to the Developer Portal

When an API version or Proxy is published, the status displays the Published status in the API Manager and Portal Manager. However, you can make changes to the Version specification and Assets or modify a Proxy, and publish the Version or Proxy again. The procedure is the same as Publishing an API version to the Developer Portal.

In the target API Version, click Publish; the procedure is the same as Publishing an API version to the Developer Portal:

1. Modify the API Version settings as required.

2. If the API has subscriptions, then modify any of the values under Subscription and Key Settings.
   IMPORTANT: If you modify these settings for an already published API, the subscriber receives an automatically generated email notification.

3. If needed, select another Snaplex to run the API version.

4. Click Publish and Exit.

5. In Portal Manager, check the status of the API Version or Proxy.

6. In the Developer Portal, search for the new API version or Proxy.

Deprecating an API Version on the Developer Portal

When you deprecate an API version, you can still update the assets used in that version and apply API policies, as well as publish, and unpublish it to the Developer Portal. However, the version in the Developer Portal is marked as deprecated, with the expectation that it could be retired.

1. In the API Management console, complete one of the following actions:

   • In API Manager, navigate to the target API version, then click Deprecate.

     

   • Click Portal Manager, scroll to the target API, and in the Actions column, click Deprecate.

     

2. Enter a message for the consumers of this API version, and click Deprecate.

   

3. To verify that the API version is deprecated check the status in the Portal Manager or Version Details of the API version.

When you deprecate an API, an email is sent to all subscribed users of the API that it is deprecated.

Retiring an API Version

When you retire an API version, API consumers can no longer view it in the Developer Portal. You can no longer modify or republish a retired API version. You must deprecate the API version before retiring it.

1. In the API Management console, complete one of the following actions:

   • In API Manager, navigate to the target API version, then click Retire.
     The Status must be Deprecated to enable the Retire button.

     

   • Click Portal Manager, scroll to the target API, and in the Actions column, click Retire.

     

2. Review the Retire API confirmation prompt, then click Retire.

   

To verify that the API version is Retired from the Developer Portal, check the status in the Version Details of the API version. The retired API version is no longer displayed in the Portal Manager or the Developer Portal.