API assets in ApiShare: introduction

In ApiShare, an API Asset represents an enterprise resource that provides access to valuable functionalities or data. Each asset is owned by an organization and a designated developer team, ensuring proper governance. API Assets serve as the foundation for creating API Products, which are tailored for target consumers and business needs.

Managing API assets

Creating an API asset

Prerequisites:

• Requires Administrator, Contributor, or equivalent custom role permissions.

• The user must belong to an organization within which the asset will be created.

Steps:

1. Navigate to the Workspace section in ApiShare.

2. Select My APIs > API Assets.

3. Click the New Asset button.

4. Enter the required details:

   • Name: Unique identifier for the API Asset.

   • Description: A brief summary of the asset’s purpose, useful for searchability.

   • Organization: Select an organization the user is a member of.

   • Group: Choose a group within the organization.

   • Owner: (Optional) Assign a business owner from the selected group.

   • Developer: (Optional) Assign a technical developer from the selected group.

   • Categories & Tags: (Optional) Select predefined classifications.

   • Integration Pattern: Choose the integration type for the asset (e.g., REST, SOAP).

   • Provider: (Optional) Select the application exposing the API Asset.

5. Click CREATE to confirm the asset creation.

Post-Conditions:

• A new API Asset is created and listed under Workspace > My APIs > Assets > In Progress > Draft.

• The asset is editable and can be proposed for activation.

Tips:

• Users with custom roles may have additional configuration options. Contact your ApiShare Administrator for details.

Duplicating an API asset

Prerequisites:

• Requires Administrator or equivalent custom role permissions.

• Only active assets can be duplicated.

Steps:

1. Navigate to Workspace > My APIs > Assets.

2. Find the active asset to duplicate.

3. Click the DUPLICATE button.

4. A copy of the asset is created with "- Copy" appended to its name.

Post-Conditions:

• The new API Asset is listed under In Progress > Draft and inherits the parent asset’s information.

Tips:

• Some fields, such as Integration Pattern, may not be editable in the duplicate.

Proposing an API asset

Prerequisites:

• The asset must be in Draft state.

• The user must have permissions to propose an asset.

Steps:

1. Navigate to Workspace > My APIs > Assets.

2. Locate the draft asset and open its details.

3. Click PROPOSE to submit it for evaluation.

4. Confirm the action and optionally leave a comment.

Post-Conditions:

• The API Asset moves to In Progress > Proposed state for evaluation.

Managing a proposed API asset

Prerequisites:

• Requires Administrator or equivalent custom role permissions.

Steps:

1. Navigate to Workspace > My APIs > Assets.

2. Locate the Proposed asset and open its details.

3. Choose an action:

   • ACTIVATE: Moves the asset to Active > Unpublished.

   • ACTIVATE AND PUBLISH: Moves the asset to Active > Published.

   • REJECT: Moves the asset to In Progress > Rejected.

4. Confirm the action and optionally add a comment.

Post-Conditions:

• The asset's status updates based on the selected action.

Directly activating (and publishing) a draft API asset

Prerequisites:

• Requires Administrator or equivalent custom role permissions.

• The asset must be in Draft state.

Steps:

1. Navigate to Workspace > My APIs > Assets.

2. Locate the Draft asset and open its details.

3. Choose one of the following actions:

   • ACTIVATE: Moves the asset to Active > Unpublished.

   • ACTIVATE AND PUBLISH: Moves the asset to Active > Published.

4. Confirm the action.

Post-Conditions:

• The API Asset is activated and, if chosen, published.

Publishing an API asset

Prerequisites:

• The asset must be in Active > Unpublished state.

Steps:

1. Navigate to Workspace > My APIs > Assets.

2. Locate the Unpublished asset and open its details.

3. Click PUBLISH.

4. Confirm the action.

Post-Conditions:

• The API Asset is now available in the API Catalog as Active > Published.

Unpublishing an API asset

Prerequisites:

• The asset must be in Active > Published state.

Steps:

1. Navigate to Workspace > My APIs > Assets.

2. Locate the Published asset and open its details.

3. Click UNPUBLISH.

4. Confirm the action.

Post-Conditions:

• The asset is moved back to Active > Unpublished.

Deprecating an API asset

Prerequisites:

• The asset must be in Active > Published or Active > Unpublished state.

Steps:

1. Navigate to Workspace > My APIs > Assets.

2. Locate the asset and open its details.

3. Click DEPRECATE.

4. Confirm the action.

Post-Conditions:

• The asset is moved to Active > Deprecated.

• Deprecated assets remain accessible but are no longer maintained.

Modifying an API asset

Prerequisites:

• Requires Administrator, Contributor, or equivalent role permissions.

Steps:

1. Navigate to Workspace > My APIs > Assets.

2. Locate the asset and open its details.

3. Make the necessary modifications.

4. Click SAVE to confirm changes.

Post-Conditions:

• The asset is updated, but its lifecycle state remains unchanged.

Tips:

• Some fields may be locked based on the asset's current state.

Productizing an API asset

Prerequisites:

• Only SOAP and REST API Assets can be productized.

Steps:

1. Navigate to Workspace > My APIs > Assets.

2. Locate the asset and open its details.

3. Click PRODUCTIZE.

4. A new API Product creation page opens, pre-filled with the asset’s details.

5. Click CREATE to finalize the product.

Post-Conditions:

• A new API Product is created and listed under My APIs > Products > In Progress > Draft.

Deleting an API asset

Prerequisites:

• The asset must be Inactive or Deprecated.

• No API Products should be associated with the asset.

Steps:

1. Navigate to Workspace > My APIs > Assets.

2. Locate the asset and open its details.

3. Click DELETE.

4. Confirm the action.

Post-Conditions:

• The API Asset is permanently removed.

Tips:

• If an asset has associated products, it must be unlinked before deletion.

API products in ApiShare: introduction

In ApiShare, an API Product is a refined and standardized version of an API Asset, designed for integration and external consumption. API Products serve as the interface between enterprise systems and external consumers, enabling seamless interactions. Each API Product follows a structured lifecycle, ensuring proper governance, visibility, and versioning.

Managing API products

Creating an API product

Prerequisites:

• Requires Administrator, Contributor, or equivalent custom role permissions.

• The user must belong to an organization within which the API Product will be created.

Steps:

1. Navigate to the Workspace section in ApiShare.

2. Select My APIs > API Products.

3. Click the New API button.

4. Choose the type of API Product creation:

   • Create a new API Product from scratch.

   • Productize an existing API Asset.

5. Enter the required details:

   • Name: Unique identifier for the API Product.

   • Version: Version of the API Product (following semantic versioning).

   • Description: A brief summary of the product’s purpose, useful for searchability.

   • Organization & Group: Define the ownership structure.

   • Owner & Developer: Assign business and technical roles.

   • Primary Provider: The application exposing the API Product.

6. Click CREATE to confirm.

Post-Conditions:

• The API Product is created and listed under Concept > Draft.

• If created from an existing asset, the product inherits the asset’s information.

Tips:

• If the API Full Configuration is enabled, an associated API Asset will also be created automatically.

Creating a new version of an API product

Prerequisites:

• The existing API Product must be Active and Published.

Steps:

1. Navigate to Workspace > My APIs > API Products.

2. Locate the API Product and open its details.

3. Click New Version and select the version type:

   • Major: Introduces breaking changes.

   • Minor: Backward-compatible updates.

   • Patch: Bug fixes or small enhancements.

4. Confirm the action.

Post-Conditions:

• A new version of the API Product is created in In Progress > Draft.

Tips:

• For Major Versions, a new related API Asset is created.

Proposing an API product

Prerequisites:

• The API Product must be in Draft state.

• The user must have permissions to propose an API Product.

Steps:

1. Navigate to Workspace > My APIs > API Products.

2. Locate the draft API Product and open its details.

3. Click PROPOSE to submit for evaluation.

4. Confirm the action and optionally leave a comment.

Post-Conditions:

• The API Product moves to Concept > Proposed state for review.

Managing a proposed API product

Prerequisites:

• Requires Administrator or equivalent custom role permissions.

Steps:

1. Navigate to Workspace > My APIs > API Products.

2. Locate the Proposed API Product and open its details.

3. Choose an action:

   • ACCEPT: Moves the API Product to In Progress > Draft.

   • REJECT: Moves the API Product to Concept > Rejected.

4. Confirm the action.

Post-Conditions:

• The API Product’s state updates based on the decision.

Publishing an API product

Prerequisites:

• The API Product must be in In Progress > Pending for Publishing.

Steps:

1. Navigate to Workspace > My APIs > API Products.

2. Locate the API Product and open its details.

3. Click PUBLISH.

4. Select the Deployment Environment (e.g., DEV, TEST, PROD).

5. Confirm the action.

Post-Conditions:

• The API Product is published in the selected environment.

• If integrated with an API Gateway, synchronization occurs automatically.

Promoting an API product

Prerequisites:

• The API Product must be in Published > Non-Production.

Steps:

1. Navigate to Workspace > My APIs > API Products.

2. Locate the Non-Production API Product and open its details.

3. Click PROMOTE to the next environment.

4. Confirm the action.

Post-Conditions:

• The API Product is promoted through environments until it reaches Production.

Tips:

• Promotion follows a strict sequence: DEV → TEST → PROD.

Deprecating an API product

Prerequisites:

• The API Product must be Published in Production.

Steps:

1. Navigate to Workspace > My APIs > API Products.

2. Locate the API Product and open its details.

3. Click DEPRECATE.

4. Optionally set a Deprecation Date.

5. Confirm the action.

Post-Conditions:

• The API Product remains usable but is marked as deprecated.

Retiring an API product

Prerequisites:

• The API Product must be Deprecated.

Steps:

1. Navigate to Workspace > My APIs > API Products.

2. Locate the API Product and open its details.

3. Click RETIRE.

4. Optionally set a Retirement Date.

5. Confirm the action.

Post-Conditions:

• The API Product is no longer accessible.

Modifying an API product

Prerequisites:

• Requires Administrator, Contributor, or equivalent role permissions.

• The API Product must not be in Retired or Transitional states.

Steps:

1. Navigate to Workspace > My APIs > API Products.

2. Locate the API Product and open its details.

3. Make necessary modifications.

4. Click SAVE.

Post-Conditions:

• The API Product is updated while maintaining its state.

Tips:

• Some fields may be locked based on the lifecycle state.

Deleting an API product

Prerequisites:

• The API Product must not be Published.

• If published, it must be Retired first.

Steps:

1. Navigate to Workspace > My APIs > API Products.

2. Locate the API Product and open its details.

3. Click DELETE.

4. Confirm the action.

Post-Conditions:

• The API Product is permanently removed.

Managing API product visibility

Prerequisites:

• Requires Administrator, Contributor, or equivalent role permissions.

Steps:

1. Navigate to Workspace > My APIs > API Products.

2. Locate the API Product and open its Visibility Settings.

3. Configure visibility by:

   • Organization Type

   • Organization Category

   • Specific Organization

   • Lifecycle Status & Deployment Environments

4. Click SAVE.

Post-Conditions:

• The API Product’s visibility is updated based on the selected criteria.