In the last section, you created an API Pack by assigning it a name and pricing type. This section covers the tasks that relate to its composition and behavior. You will learn how to package and bundle APIs in order to make them available to the Consumers.
Editing process for an API Pack involves:
Adding resources/operations from Approved or Published APIs
Attaching security and Usage Policies to resources/operations
Monetizing APIs by adding Usage Plans
Branding and publishing APIs
An Edited and Approved API Pack becomes available to the developers in the API Store under the selected Category.
Before you begin:
It is assumed that you have completed the tasks enumerated in the earlier sections.
It is assumed that you have the approval(s) for the API Version(s) that you plan to add to the Pack and the States of these API Versions display as “Approved.”
The API Packs Configuration screen consists of tabs for editing and adding Pack Contents, Usage Plans, Documentation and Branding. For Admin and Technical user roles, the Usage Plans and Branding tabs are not available.
The fields marked with asterisks are mandatory.
Common Tasks
Following are the common tasks identified for this section:
Navigating to the REST/SOAP/GraphQL API Packs Configuration screen
To navigate to the API Packs Configuration screen:
Navigate to the API Packs screen
In the API Packs screen, click the row that has the REST or SOAP API Pack that you want to configure. The API Packs Configuration screen displays. REST, SOAP and GRAPHQL API Packs can be differentiated by the ‘R’,’S’ and ‘G’ present on their respective icons.
Descriptions about an API Pack forms part of the information that is made available in the Developer portal. API Consumers start using an API based on the information that you provide in the Descriptions field. The descriptions should therefore be as clear and concise as is possible.
Note
Both the Short Description and Detailed Description fields in the Overview tab of the API Pack Configuration screen are mandatory.
To add Descriptions to an API Pack:
Navigate to the REST API Packs Configuration screen.
In the REST API Packs Configuration screen, click the Overview tab. The Overview tab screen displays.
You can omit this step if you have navigated here from the APIs Packs screen as the Overview tab displays by default.
In the Short Description box, type or edit a short description. The Short Description box displays the short description that you typed in the Add API Pack dialog box when you created the API Pack earlier.
In the Detailed Description box, type a detailed Description.
Click Save As Draft to save changes and finish adding the Descriptions.
You created/edited resources/operations for APIs when we were in the topics: Add API Resources and Edit API Resources. These resources can now be used to decide the composition of a Pack. All the resources from Approved and Published API Versions are available for forming Pack Contents for an API Pack.
To add Resources from Approved or Published APIs to a REST API Pack:
Navigate to the API Packs Configuration screen.
In the API Packs Configuration Screen, click the Pack Contents tab. The Pack Contents tab displays a list of all resources/operations that have been added to the Pack. In case you are adding Pack contents to the API Pack for the first time, an empty list with the message: “There are no pack contents added yet” displays.
Click Add Resources to Pack to add new resources to the Pack.
Click the API drop-down list to select the REST API that has the resource(s) you want to add to the Pack Contents list. The latest version number of the selected API auto-fills in the Version box and the list of resources from that API Version displays under Select Resources For Pack below. Click the API box to display the drop-down list if you need to view the drop-down list again after selection.
Fig. 3.239 Add Resources to Pack dialog - Select API¶
Note
If there are no Approved or Published version of the selected API, the Version drop-down displays a “No Matches” message
Click to select the check boxes corresponding to Resource names that you want to add to the API Pack. Alternatively, you can click the header check box to select all resources in one go.
Note
By default, the Version drop-down box displays the most recent version of the Approved and Published API. To choose a different Version, click the Version drop-down box.
Click Add to add the selected resources to the API Pack. The Add Resources to Pack dialog box closes. The newly added Resource(s) now displays in the Pack Contents list.
Repeat steps 3 to 6 to add more resources from another REST API.
Click Save as Draft to save the newly added Pack Contents. A notification message “API Pack details were updated successfully” displays indicating that the newly added Pack contents are saved successfully.
Note
The Add Resources to Pack option is enabled and hence available for API Pack versions that are in Draft State.
To add Operations from Approved or Published APIs to a SOAP API Pack:
Navigate to the SOAP API Packs Configuration screen.
In the SOAP API Packs Configuration Screen, click the Pack Contents tab. The Pack Contents tab displays a list of all Operations that have been added to the Pack. In case you are adding Pack contents to the API Pack for the first time, an empty list with the message: “There are no pack contents added yet” displays.
Click Add Operations to Pack to add new Operations to the Pack.
Click the API drop-down box to select the API that has the Operations that you want to add to the Pack Contents list. The latest version number of the selected API auto-fills in the Version box and the list of Operations from that API Version displays under Select Operations For Pack below.
Click the API box to display the drop-down list if you need to view the drop-down list again after selection.
Note
If there are no Approved or Published API’s, the drop-down will not display anything.
The check boxes corresponding to Operation names are disabled as all the Operations under an API are selected by default and are added to the API Pack.
Note
By default, the Version drop-down box displays the most recent version of the Approved and Published API. To choose a different Version, click the Version drop-down box.
Note
All the Operations that need to go into an API pack can only be added as a whole and cannot be selected individually.
Click Add to add the selected Operations to the API Pack. The Add Operations to Pack dialog box closes. The newly added Operation(s) with its API now displays in the Pack Contents list.
Repeat steps 3 to 6 to add more Operations from another API.
Click Save as Draft to save the newly added Pack Contents. A notification message “The API Pack details were updated successfully” displays indicating that the newly added Pack contents are saved successfully.
Note
The Add Operations to Pack option is enabled and hence available only for API Pack versions that are in Draft State.
To add Resources from Approved or Published APIs to a GraphQL API Pack:
Navigate to the GraphQL API Packs Configuration screen.
In the GraphQL API Packs Configuration Screen, click the Pack Contents tab. The Pack Contents tab displays a list of all Resources that have been added to the Pack. In case you are adding Pack contents to the API Pack for the first time, an empty list with the message: “There are no pack contents added yet” displays.
Click Add Resources to Pack to add new Resources to the Pack.
Click the API drop-down box to select the API that has the Resources that you want to add to the Pack Contents list. The latest version number of the selected API auto-fills in the Version box and the list of Resources from that API Version displays under Select Resources For Pack below.
Click the API box to display the drop-down list if you need to view the drop-down list again after selection.
Note
If there are no Approved or Published API’s, the drop-down will not display anything.
Click to select the check boxes corresponding to Resource names that you want to add to the API Pack. Alternatively, you can click the header check box to select all resources in one go.
Note
By default, the Version drop-down box displays the most recent version of the Approved and Published API. To choose a different Version, click the Version drop-down box.
Click Add to add the selected resources to the API Pack. The Add Operations to Pack dialog box closes. The newly added Resource(s) with its API now displays in the Pack Contents list.
Repeat steps 3 to 6 to add more resources from another GraphQL API.
Click Save as Draft to save the newly added Pack Contents. A notification message “The API Pack details were updated successfully” displays indicating that the newly added Pack contents are saved successfully.
Note
The Add Resources to Pack option is enabled and hence available for API Pack versions that are in Draft State.
3.10.3. Delete Resources or Operations from an API Pack¶
A Resource or Operation can be deleted directly from an API Pack if:
The Resource/Operation is not part of a Usage Plan
The API Pack to which it belongs is in its Draft state
If a Resource/Operation is part of a Usage Plan, you need to unlink/delete the Resource or Operation from the Usage Plan before you can go ahead and delete it from the Pack.
To learn about how to unlink a Resource or Operation from the Usage Plan, visit the topic:
‘Unlink a resource or operation from usage plan’ in Create a Usage Plan.
Note
In the case of a SOAP API Pack, if you have added Operations from more than one version of an API, delete the Operations of a single version and then click Save as Draft. Repeat for other versions.
To delete a Resource from an API Pack:
Navigate to the API Pack Configuration screen.
In the API Configuration screen, click the Pack Contents tab.
Click the Delete icon in the row that has the Resource/Operation that you want to delete. A notification message displays. Click OK to remove the Resource/Operation from the Pack Contents list.
Click Save as Draft to save changes.
Next Steps
In the next section, we will take you through the steps needed to create a Usage Plan so you can bundle and add Usage Plans for an API Pack.
API Resources/Operations are bundled and presented as part of a Subscription plan in a way that allows maximum benefits to its Consumers. A Subscription Plan has all the relevant resources/operations needed by developers for developing an application.
When you think about monetizing an API Pack constituted from a focused set of resources/operations, you also need to have a Plan that bills Consumers based on its usage. Usage Plans enable the developers to choose from among different Plans. Each plan has one or more Usage Policies that define the Usage Limits through Rate Limits and Throttling. The Policies specify the number/volume of API calls that a Consumer is permitted to make during a specified time.
A Usage Plan is a set of Policies that defines the level of service that is offered to the subscriber, and through which API owners can bill and generate revenue. You can set your Usage Plans based on the potential traffic an API is able to generate.
Usage Plans can have security policies and usage policies attached to them. Usage Policies specify the limits of use for a plan. Attaching a usage policy to a plan limits the use of APIs falling under the plan. The limit from the policy applies separately to each consumer subscription made under the plan. This is because the usage policies attached to the plan are copied as-is to each subscription made against the plan. It is important to note here that you can override usage policies that are attached to a plan by configuring subscription level settings. To learn more about how you can override usage policies at subscription level, visit: Configure Subscription-level Settings.
The Developer portal in its API store displays the details of the main Usage Plan inside the API Pack box (main Usage Plan is the topmost plan in the Usage Plan Display Order. You can learn more about Display Order in the topic, Modify Usage Plan Display Order and all Plan details in the Pack detail page. As a usage-based monetization strategy can have multiple Usage-based plans, you need to identify and mark the main Usage Plan. By default DigitMarket™ API Manager assumes the first plan that is created under a Pack to be the main usage plan, and displays it inside the API Pack box in the API store. All the plans display in the Plans tab of the API Pack Details page in the Developer portal.
Note
A Usage Plan can be created only if the API Pack to which it belongs is in its Draft State.
To create a Usage Plan:
Navigate to the Usage Plans tab of API Packs Configuration screen.
Click New Plan to add a new Usage Plan. The Add Plan dialog box displays.
Plan name menu has collapsible sub-menus. Clicking the Plan name toggles between displaying and hiding the following sub-tabs in the case of monetized strategies such as Usage-based, Revenue-sharing and Transactional:
Resources(REST and GraphQL)/Operations(SOAP)
Policies
Pricing
Documentation
Gateway
Data Recording
Fault Config
In the case of Non-monetized strategy, clicking the Plan name toggles between displaying and hiding the following sub-tabs
Resources(REST and GraphQL)/Operations(SOAP)
Policies
Limits
Documentation
Gateway
Data Recording
Fault Config
It also displays a summarized view of the Plan in the Usage Plan Summary screen and a Sandbox Plan.
Note
Data Recording is currently not supported in GraphQL.
Add Resources or Operations to a Usage Plan
By default, the Resource sub-tab/Operations sub-tab displays all the resources/operations that are added to the Pack through Add Resources to Pack/Add Operations to Pack in the Pack Contents tab. Using the task stepped out here, you can select the resources/operations from the Pack that you want added to the Usage Plan.
To add Resources/Operations to a Plan:
Navigate to the Usage Plans tab of API Packs Configuration screen.
In the Usage Plans tab, click the Plan name to display collapsible tabs and the Plan Summary panel.
Click the Resources/Operations tab to display the resources/operations that have been added to the currently open API pack.
Click to select the check box(es) corresponding to the resources/operations that you want included in the Usage Plan. The Select All checkbox next to the Method header allows you to select all the resources/operations.
Fig. 3.254 API Pack Plan - Resources/Operations select¶
Click Save as Draft to save changes. A notification message: “Resource details for the Usage plan were updated successfully”(REST)/”Operation details for the Usage plan were updated successfully”(SOAP) displays indicating that the resources/operations have been successfully added to the Usage Plan.
Note
The Save as Draft option is available only when the Usage Plan is in its draft state.
Unlink a Resource or Operation from Usage Plan
To unlink a Resource or Operation from a Usage Plan:
Repeat steps 1 to 3 from the earlier task: ‘Add Resources or Operations to a Usage Plan’.
Click the selected check boxes to deselect the resources/operations that you want to unlink from the Plan.
Click Save as Draft to save changes.
Attach a Plan Level Usage Policy to a Usage Plan
Plan-level Usage Policies are Usage Policies that are applied commonly to all the resources/operations present in a Plan. The policies that are attached to a Usage Plan shall be copied and applied as is to all the subscriptions that fall under the Plan. The usage limits from the attached policies are enforced separately to each consumer subscription made against the plan.
To add a Plan level Usage Policy:
Navigate to the Usage Plans tab of API Packs Configuration screen.
In the Usage Plans tab, click the Plan name to display collapsible sub-tabs and the Plan Summary panel.
From the collapsible sub-tabs, click Policies to display the Policies configuration options.
Under Plan level policies, click Usage Policy accordion tab to open the Usage Policy section. A list of usage Policies attached to the Plan displays. In case you are attaching policies newly to a Plan, the message, “There are no policies added yet’ displays.
Click the Assign Policy button to assign a new policy to the Plan. The Plan Level - Select Existing Usage Policies dialog box displays.
Click to select the check box corresponding to the Usage Policy you want to apply to the Plan as a whole.
Note
Usage Policies that are in Approved and Published states appear in the Plan Level - Select Existing Usage Policies dialog box for selection but you can only send a plan for approval that has an Approved or Published Usage Policy attached to it and does not have any Usage Policy in Draft State.
Click Assign to add the Plan-level Usage Policy to the Plan and close the Plan Level - Select Existing Usage Policies dialog box. The Plan name displays in the Usage Policy section indicating that the Policy has been attached to the Plan.
Click Save as Draft to finish adding the Plan level Usage Policy to the Plan.
You can add any number of Plan-level Usage Policies, provided you keep a manual check over the period to which each one of them apply - keeping a check to see that none of the Plans, so added, overlap each other in the time duration for which they apply.
In case you have added both Rate Limiting and Throttling Usage Policies to a Plan, and they apply to the same time period, the Rate Limiting Policy will take precedence over the Throttling one, which means that at run time Rate Limiting policy will be enforced.
In case you have configured policies for a plan (at both Plan level and Resource level), and also for its Subscription (at both Plan level and Resource level) then Subscription (Resource level) policy will override all the other policies.
Policy configuration precedence hierarchy is: Subscription level (Resource level policy) > Plan level (Resource level policy)> Subscription level (Plan level policy) > Plan level (Plan level policy)
To add a Resource-level/Operation-level Usage Policy, visit ‘Attach a resource or operation level policy to a usage plan’ below.
Note
When you have the same policy as the Plan-level and Resource/Operation level Policy, the Resource/Operation level Policy is applied at runtime.
Adding Plan Level Authentication
Authentication mechanism for a plan is used for granting access to the API resources of the plan that the user has subscribed. Once the user configures the authentication type and assigns the values (wherever applicable), the user will be able to access the plan and consume the resources. As a user, under the Plan Authentication you can configure the following authentication types to consume the API resources:
Subscription key
IP Whitelisting
Header key
Query parameter
Subscription key:
Subscription key is a key that is required for processing authentication requests. This is the default authentication mechanism that is available for getting access to the resources. User can change the default by choosing a different authentication mechanism from the available options.
IP Whitelisting:
IP Whitelisting is a way to limit access control only to a list of trusted IPs addresses. Publisher users or Developer users can add the list of IP addresses, or define the IP address range that can be allowed to access the resources at the time of subscription.
Header key:
Header key is the key that needs to be passed in the request header to consume an API. Header key consists of a key-value pair. The Header key (or header name) can be defined when selecting the authentication type. The value can be defined by Publisher users or Developer users at the time of subscription.
Query Parameter:
Query parameter is the parameter that needs to be passed in the request URL. Query parameter consists of a key-value pair. The Query parameter key (or Query parameter name) can be defined when selecting the authentication type. The value can be defined by Publisher users or Developer users at the time of subscription.
Note
Only users with Publisher rights (Publisher User) can define the plan with one of the above authentication types. Plan Authentication type (and key wherever applicable) can only be set by a Publisher in the Publisher Portal. The values can be configured at the time of Subscription either in the Publisher Portal or Developer Portal.
Plan level subscription authentication model is applicable only for Production plan. Sandbox plan has subscription key authentication model by default.
Gateway will process the request to authenticate the service request with the below hierarchy: Subscription key > IP Whitelisting > Header key > Query parameter
To set the plan level authentication:
Navigate to the Usage Plans tab of API Packs Configuration screen.
In the Usage Plans tab, click the Plan name to display collapsible tabs below.
Click the Policies tab to display the Plan-level Policies.
From the drop-down list, select the Authentication Type. The available option are: Subscription-key, Ip-white listing, Header key, Query parameter. If you have selected Header key or Query parameter authentication method, additionally you need to specify the Header key value and the Query key value respectively.
Fig. 3.257 Plan Authentication - Subscription-key¶
Fig. 3.258 Plan Authentication - Ip-white listing¶
If a plan has an active subscription, it will not allow editing of plan level authentication method. If the authentication key is not defined then the key can be defined on each subscription
Note
After a subscriber subscribes to a plan, a subscription key will be generated only if the plan authentication type is selected as Subscription-key.
Attach a Resource or Operation Level Policy to a Usage Plan
The policies that are attached to a Usage Plan shall be copied and applied as is to all the subscriptions that fall under the Plan. The Usage limits from the attached policies is enforced separately to each consumer subscription made against the plan.
If you have already added Named Usage Policies as needed, you can go ahead with attaching them to Plans. If you do not have a Named Usage Policy that you want to add to the Plan, you need to create and edit a Named Usage Policy from the Create a Named Usage Policy and Edit a Named Usage Policy in the Main Navigation menu.
The Policies tab has accordion tabs for each Policy, wherein clicking a Policy tab toggles between expanding and collapsing relevant tab details.
Add Security Policy for a REST Pack
A Security Policy applies to only those resources that are added to the Plan.
To display the resources that are covered by a Security Policy, click the Security Policy tab.
To attach a security policy to a Resource:
Navigate to the Usage Plans tab of API Packs Configuration screen.
In the Usage Plans tab, click the Plan name to display collapsible tabs below.
Click the Policies tab to display the Plan-level and Resource-level Policies in accordion tabs.
Under Resource-level Policies, click Security Policy accordion tab to open the Security Policy section. The list of resources that have been added to the Plan displays. Each row represents a Resource.
If you select Policy Type as oAuth, enter the Username header key.
(Optional) Click the Access Token check box to select it.
(Optional) Click the Client ID check box to select it.
The Username header key header key value is the username that is required to be validated in the active directory against the oAuth token. This validation is only applicable if the Password Grant Type oAuth Authorization is selected while generating the token. For more information, refer the topic ‘Using OAuth in API Connect’ in the section Authentication. Upon successful authentication, the Gateway will attach the Client ID and the Access Token (invoked from the Gateway property file) in the request header before sending it to the backend.
If the Username header key box is left blank, the oAuth token will not be validated against the username.
Click Save as Draft to save changes.
Note
You can add the credentials for Basic Authentication using the main menu option: Subscriptions. Learn more on this in the topic: Configure Subscription-level Settings.
Assign a Resource level or Operation level policy to a Usage Plan
A Usage Policy is applied to only those Resources/Operations that are added to the Plan.
To display the resources/operations that are covered by the Usage Policy, click Resource level Policies/Operation level Policies tab.
To attach an existing Usage Policy to a Resource/Operation:
Navigate to the Usage Plans tab of API Packs Configuration screen.
In the Usage Plans tab, click the Plan name to display collapsible tabs below.
Click the Policies tab to display the Policies in an accordion menu.
Click Usage Policy accordion tab to open the Usage Policy section. The list of resources/operations added to the Plan displays. Each row represents a Resource/Operation.
Click the edit icon next to the Resource/Operation name to attach an existing policy to the Resource/Operation. The Resource Level – Select Existing Usage policies (REST)/ Operation Level – Select Existing Usage policies (SOAP) dialog box displays.
Click the check box(es) corresponding to the Usage policy(ies) that you want to attach to the Resource/Operation. You can attach multiple policies to a Resource/Operation provided there are no runtime overlaps with respect to the time duration for which they are enforced.
Following steps are common to all Monetization Strategies:
Choose plan as Paid.
Under Monetization Rules, click the Currency Type drop-down box to select the currency type for the Pricing information. The currencies available are USD, EURO and INR.
The Currency type for the form changes to the selected Currency type.
Under One Time Fees, in the Signup Fee box, type the sign-up fee. Sign-up fee is the fee that the developer user needs to pay for registering to a pack plan.
Under One Time Fees, in the Termination Fee box, type the Termination fee. Termination fee is the amount that will be applicable once the subscriber/consumer chooses to unsubscribe from a plan midway through the plan validity period.
Under Subscription Fees section, click the Subscription Duration drop-down list to select the number of months for which the subscription will be applicable.
Under Subscription Fees, in the Subscription Fee box, type the subscription fee that will be applicable for the number of months as selected from the Subscription Duration drop-down box from the previous step.
Under Subscription Fees, click the Subscription Expiry - Developers can enable auto-renewal drop-down list. Select Yes to allow the Developer users the option to enable auto renewal at the time of subscribing for a Pack plan from the Developer portal. Select No to deny them this option.
The fields in the Revenue Limits/Quotas section are contextual to the Monetization Strategy selected:
Monetization Strategy: Usage-based
Under Usage Limits/Quotas, type the maximum number of requests allowed per month in the Maximum Number of Requests Allowed box.
If you’re looking for unlimited requests, turn on the Unlimited requests toggle.
Under Transaction Limits/Quotas, type the path to the field in the message payload that contains the transaction value in Xpath box. The path helps the Publishers keep a track of the transaction value involved in any transaction. This information is used for billing and data recording purposes.
Following steps are common to all Monetization Strategies:
In the Comment box, type any comment that you want to add to the Usage Plan.
Click Save as Draft to save changes.
Note
For the Usage-based monetization strategy, when there are multiple plans, the first plan that you create will be the main usage plan that displays inside the API Pack box in the API store.
The steps below apply to the Non-monetized strategy.
To add Limits to a Usage Plan:
Navigate to the Usage Plans tab of API Packs Configuration screen.
In the Usage Plans tab, in the left panel, click the Plan name to display collapsible Plan tabs.
Click the Limits sub-tab to display the Monetization Rules form.
In Plan Documentation, click Choose File to attach a file from your computer that has the documentation related to APIs covered under the Plan.
In Sample Data, click Choose File to attach a file from your computer that has the examples and samples for trying out APIs covered under the Plan.
Click Save as Draft to save changes.
Map Usage Plan to Gateways
In the Map to Gateway section, you can map the Usage Plans to all, single or multiple Gateways.
The Select the Gateway you want to map drop-down displays the list of Gateways that are configured for the publisher organization. From the Select the Gateway you want to map drop-down, choose the Gateway to which you want to map the Usage Plan. The Gateways you select will appear at the top of the drop-down. You can remove the selected Gateways by clicking the .
For a Production Usage Plan, Production Gateways will be available in the drop-down list to map and for the Sandbox Usage Plan Sandbox Gateway will be available in the drop-down.
The Usage Plan will be mapped only to the selected Gateways. If the Plan has a dependency on API then those APIs will also be mapped along with the Plan.
You can also map the Usage Plan from the Plan tab of the selected Gateway. Refer Plan.
Map Dev Org to Gateways
Note
Dev Org section is enbabled only if the Plan is Paid and the Gateway is mapped to the plan.
Click the Edit icon to edit the Developer Organization Gateway and Click the Delete icon to delete the Developer Organization Gateway if necessary.
Enable Data Recording
The Data Recording sub-tab allows the user to manage data recording activities for each resource/operation that is added to the Usage Plan. By default, the script is copied from the default script entered in the resource/operation when creating the API. The script that is included in a Usage Plan for each Resource/Operation is editable independent of the script at the API-level. If enabled, the script used in data recording of Resource/Operation at the Usage plan level is processed for that Resource/Operation and the resultant output data is logged for that Resource/Operation only. In case a particular Resource/Operation is found in more than one usage plan, scripts in each of such cases are processed and data logged in each case separately.
To enable Data Recording:
Navigate to the Usage Plans tab of API Packs Configuration screen.
In the Usage Plans tab, in the left panel, click the Plan name to display collapsible Plan tabs.
Click the Data Recording tab to display the Data Recording screen.
Fault configuration can be set only for Plans in Draft state.
Click Fault Configuration accordion tab and then click Content Type. You can overwrite the configured Content Type at Plan level and for all/individual Resources. Click the Overwrite toggler to activate overwrite and click again to disable overwrite and retain the default Content Type settings. Upon enabling Overwrite, the Content Type options at Plan Level and for all/individual Resources will be enabled.
Click to select the required Content Type (JSON/XML/PlainText) option to be configured at Plan Level and for each all/individual Resources and then click Save as Draft. This will overwrite the default Content Type settings.
Next, click Fault Structure accordian tab. You can overwrite the configured Fault Structure at Plan level and for all/individual Resources. Click the Overwrite toggler to activate overwrite and click again to disable overwrite and retain the default Fault Structure settings. Upon enabling Overwrite, the Fault Structure options at Plan Level and for all/individual Resources will be enabled.
(Optional) Edit the JSON/XML/PlainText Fault box to make any required changes to the Fault template at Plan Level and for all/individual Resources and then click Save as Draft to save the changes.
Next, click Scenario-wise Fault Message. You can overwrite the configured Fault Message at Plan Level and for all/individual Resources. Move the Overwrite toggler to the right to activate overwrite and do the inverse to retain the default Fault Message settings. Upon enabling Overwrite, the Fault Message options at Plan Level and for all/individual resources will be enabled.
Note
If Fault Configuration is overwritten for All Resources of a Plan, then the fault configuration of All Resources will be applicable for each Resource.
Fault configuration can be set only for Plans in Draft state.
Click Fault Config accordion tab and then click Fault Structure. You can overwrite the configured Fault Structure at Plan level and for all/individual Operations. Click the Overwrite toggler to activate overwrite and and click again to disable overwrite and retain the Default Fault Structure settings. Upon enabling Overwrite, the Fault Structure options for Plan and for all/individual Operations will be enabled.
(Optional) Edit the XML Fault box to make any required changes to the Fault template at Plan level and for all/individual Operations and then click Save as Draft to save the changes.
Next, click Scenario-wise Fault Message. You can overwrite the configured Fault Message at Plan level and for all/individual Operations. Click the Overwrite toggler to activate overwrite and click again to disable overwrite and retain the default Fault Message settings. Upon enabling Overwrite, the Fault Message options at Plan level and for all/individual Operations will be enabled.
Note
If Fault Configuration is overwritten for All Operations of a Plan, then the fault configuration of All Operations will be applicable on each Operation.
Fault configuration can be set only for Plans in Draft state.
Click Fault Structure accordian tab. You can overwrite the configured Fault Structure at Plan level and for all/individual Resources. Click the Overwrite toggler to activate overwrite or click again to disable overwrite and retain the default Fault Structure settings. Upon enabling Overwrite, the Fault Structure options at Plan Level and for all/individual Resources will be enabled.
(Optional) Edit the JSON Fault box to make any required changes to the Fault template at Plan Level and for all/individual Resources and then click Save as Draft to save the changes.
Next, click Scenario-wise Fault Message. You can overwrite the configured Fault Message at Plan Level and for all/individual Resources. Click the Overwrite toggler to activate overwrite or click again to to disable overwrite and retain the default Fault Message settings. Upon enabling Overwrite, the Fault Message options at Plan Level and for all/individual resources will be enabled.
Note
If Fault Configuration is overwritten for All Resources of a Plan, then the fault configuration of All Resources will be applicable for each Resource.
You need to set the visibility of a Usage Plan to manage a Developer group’s accessibility to the Plan. For you to be able to set visibility to a Usage Plan for a Group, you must first set API Pack-level visibility for that Group. This is because a Group that has permission to view an API Pack shall only be allowed to view the plans contained in it.
Once you are through with adding resources/operations, attaching Usage Policies, adding Pricing, attaching documentation for the Plan and Pack, and branding and selecting the Usage Plan display order (in the case of Usage-based monetization strategy), the Plan is ready to be send for approval. At the minimum, before sending a plan for approval, you must check if the following details are present for the Usage Plan:
Resource details
Term validity
Usage Limits for Usage-based strategy or Transaction/Revenue limit for Transactional/Revenue-sharing strategy
All attached policies have Approved or Published states
For Packs that have Usage-based Monetization Strategy and multiple Usage Plans, you need to send all Usage Plans for approval for you to be able to send the API Pack for approval. If there is even one Usage Plan that is still in the Draft State, the API Pack is not allowed to be send for Approval.
To send a Usage Plan for Approval:
Navigate to the Usage Plans tab of API Packs Configuration screen.
In the Usage Plans tab, click the Plan name to display the collapsible sub-menu and Usage Plan Summary screen.
In the Usage Plan Summary screen, click the Usage Plan Action icon to display the Usage Plan Action menu.
Click Submit for Approval to send the Usage Plan for approval.
Once the Usage Plan is approved, the Usage Plan’s State changes from Submitted for Approval to Approved.
Note
All the Plans under a Pack have to be in the Approved or Published State for you to be able to send the Pack for approval.
An Approved Usage Plan displays in the Gateway Sync screen, from where it needs to be propagated and made operational in the Gateway. Once the Plan is propagated to the Gateway, the State of the Plan changes to the Published state. The Published state of the Plan (and other plans in the case of Usage-based strategy) allows you to send the Pack for approval.
Note
All the Policies that you have attached to the Plan either at the Plan-level or Resource or Operation-level have to be in the Approved or Published State for you to be able to send the Plan for approval.
If a Sandbox-enabled API is added to a pack, a Sandbox plan is created by default for that API pack. For details visit: Configuring API Pack for Sandbox.
If user approves a version without maping any gateway, the message displays as shown below.
The Usage Plan State changes from Published to Published. Awaiting Approval for Editing.
Fig. 3.314 Published. Awaiting Approval for Editing¶
The Usage Plan is sent for approval and once a Publisher user approves it, the state of the Usage Plan changes to draft. You can now edit the Usage Plan.
Once you are done with making changes to the Usage Plan, send the Usage Plan for Approval. When approved, the State of the Usage Plan changes back to the Approved state.
To propagate the Usage Plan and make it operational, complete the tasks in the section: Synchronize Changes.
3.10.4.8. Discard Changes after opening a Usage Plan for Editing¶
You can discard the draft and revert to earlier Approved Usage Plan if you change your mind about revising the Usage Plan after opening it for editing.
To Discard the Draft after opening a Usage Plan for editing:
Navigate to the Usage Plans tab of API Packs Configuration screen.
In the Usage Plans tab, click the Plan name to display Usage Plan Summary screen.
In the Usage Plan Summary screen, click the Usage Plan Action icon to display the Usage Plan Action menu.
In the Usage Plan Action menu, click Discard Draft to submit the request for discarding the API Pack draft.
There can be more than one Usage Plan in the case of Plans based on Usage-based monetization Strategy. You can set the order in which they display in the Developer portal. By default, the plans display in the order of their creation.
To modify the Usage Plan Display Order, complete the task below:
To modify Usage Plan Display Order:
Navigate to the Usage Plans tab of API Packs Configuration screen.
When there are more than one Usage Plan, Usage Plans tab Summary screen displays Modify Usage Plans Display Order panel. Alternatively, in the Usage Plans tab, click a Plan name to bring it to the collapsed state.
In the Usage Plans tab Summary screen, under Modify Usage Plans Display Order, drag and drop the Usage Plan buttons to re-arrange the order of their display in the Developer portal.
Once users are done creating usage plans and then publishing those plan, they need to test the API packs for functionality. Apart from testing APIs, users can also run tests on their API packs without needing to use third-party dependencies.
In DigitMarket™ API Manager, users can test their API packs by invoking the following methods:
GET: Allows users to obtain information
POST: Allows users to add new information
PUT: Allows users to replace exiting information
PATCH: Allows users to update certain exiting information
DELETE: Allows users to delete exiting information
OPTIONS: Allows users to request for information about the communication option available for a resource
Note
Test feature is only available for published REST/SOAP plans.
To test a Usage Plan for REST Pack:
Navigate to the Configuration screen of a published Usage plan and click Test.
Documentation that you attach to an API Pack is made available in the Developer portal at the Pack-level. The documentation file can be an HTML or Zip file. If you are using a Zip file, make sure you include an index.html file in the root folder.
To attach documents to an API Pack:
Navigate to the Documentation tab of API Packs Configuration screen.
Click the Choose File button alongside Pack Documentation to attach a file from your computer that has the documentation related to APIs covered under the Pack.
Click the Choose File button alongside Sample Data to attach a file from your computer that has the examples and samples for trying out APIs covered under the Pack.
Click the Choose File button alongside Pack Overview to attach a file from your computer that has the overview description for the Pack.
You can customise the look and feel of API Packs in the Developer portal. Customizing the background images and pack icons enables you to add branding to your API Packs in the Developer portal. You can add a background image, a banner image and an icon to go with an API Pack. You can also select a Category from the Category Tree to which you want to assign an API Pack. The Category tree (as explained later) is used to display categories in the API Store.
Before you begin:
The Branding tab is available only to the business-level users.
The fields marked with asterisks are mandatory.
To apply Branding to your API Pack in the Developer portal:
Navigate to the API Packs Configuration screen.
In the API Packs Configuration screen, click the Branding tab.
Open a high-resolution PNG or JPG image for your background image. The dimension for the image should ideally be 265 x 125 pixels. The background image you choose here will be used as the background for the API Pack Display box in the API Stores and the API Pack Details page in the Developer portal.
The chosen image file name displays alongside the Choose File button indicating that the background image is uploaded successfully.
In the Banner Image: field, click Choose File to choose an image file (JPG, PNG) from your local machine. The banner image you choose here will be used as the banner for the API Pack Details page in the Developer portal.
Open a high resolution image for your banner image. The dimension for the image should ideally be 1142 x 179 pixels.
The image file name displays alongside the Choose File button indicating that the banner image is uploaded successfully.
In the Icons: field, click Choose File to choose an image file (JPG, PNG) from your local machine to represent an icon for the API Pack. The icon image that you choose here will be used as the icon image for the API Pack Display box in the API Stores page in the Developer portal.
Open an image for your icon image. The dimension for the image should ideally be 41 x 41 pixels.
The image file name displays alongside the Choose File button indicating that the icon image is uploaded successfully.
In the Select Category field, Click Category to display the Branding - Select Category dialog box.
Click to select the Category you want to assign to the API Pack. The Category to display the currently open API pack in the Developer portal is based on the category you select here.
You can also add/delete/edit a category from the Category Tree dialog box.
To learn more on how to add/delete/edit categories to the Category Tree, visit: Manage API Pack Categories.
Click Update once you are done with selecting the category. The selected category displays alongside the Category Tree indicating that the category has been assigned to the currently open API Pack.
Note
In the absence of user-uploaded images, the default images apply.
Click Save as Draft to save changes to the Branding tab.
Next Steps
The next section takes you through the steps necessary to manage Visibility of an API Pack.
The API Pack Configuration screen allows you to select the Publisher and Developer Group(s) that have access permissions to view an API Pack. The Visibility option available from the API Pack Action menu helps associate Publisher and Developer groups with a Pack. Once a Developer Group is associated with a Pack, all the members of that Group can view and subscribe to Plans under that Pack.
To select which Publisher Groups should be permitted access to the currently open API pack:
Navigate to the API Packs Configuration screen.
In the API Packs Configuration screen, click the Action icon to display the API Pack Action Menu.
Fig. 3.342 API Pack Action Menu - Manage Visibility¶
In the API Pack Action Menu, click Manage Visibility to display the Manage Visibility dialog box with two panels named For Publishers and For Developers.
In the For Publishers panel, click to select the check box(es) corresponding to the Publisher Group(s) for which you want to allow access to the currently open API Pack.
Click Submit to save changes. A notification message “API Pack visibility details were updated” displays.
To select which Developer groups are permitted access to the currently open API pack:
Navigate to the API Packs Configuration screen.
In the API Packs Configuration screen, click the Action icon to display the API Pack Action Menu.
Fig. 3.344 API Pack Action Menu - Manage Visibility¶
In the API Pack Action menu, click Visibility to display the Manage Pack Visibility dialog box with two panels named For Publishers: and For Developers:.
You need to publish all the Usage Plans that have been created within a API Pack for you to be able to publish the API Pack. An API Pack is restricted from being send for approval if any Usage Plan remains in the Draft or Approved State, which means that all the Plans under the Pack must be in the Published State.
To publish an API Pack:
Navigate to the API Packs Configuration screen.
Click the Action icon . The API Pack Action menu displays.
In the API Pack Action menu, click Submit For Approval to send the Draft API Pack for approval if the Automatic Workflow for the Pack for the user is enabled, or click Publish to publish the API Pack if the Automatic Workflow for the Pack for the user is enabled.
In case any of the mandatory fields in the Overview, Pack Contents, Documentation and Branding tabs is not filled or any of the Usage Plan is not Approved, a notification message displays, and you are not allowed to send the Pack for approval.
The API Pack is sent for approval if Automatic Workflow for the API Pack is not enabled. After the Pack is approved, the state of the API Pack changes to Published.
If Automatic Workflow for the Pack for the user is enabled - and since there is no sync for API Packs - its State changes to Published and all the Plans under the Pack is now available on the Developer portal.
Published API Packs are API Packs that are ready to be subscribed and consumed by the Developer community. You cannot directly edit an published API Pack to, for instance, add another Resource/Operation from an API. To enable editing, you have to send the Pack for edit approval using the “Open For Editing” option that is available from the API Pack Action menu.
To enable editing of an Approved API pack:
Navigate to the API Packs Configuration screen.
Click the API Pack Action icon . The API Pack Action menu displays.
In the API Pack Action menu, click Open for Editing.
The API Pack is sent for approval and once the Publisher user approves it, the state of the API Pack changes to Draft. You can now edit the Pack as it has the Draft State.
Once you are done with making changes to the API Pack, submit the API Pack for approval.
After the approval, the API Pack’s State changes to Published.
To make the changes operational complete the tasks enumerated in the section: Gateway Sync.
The user can search for an API Pack using the Search feature present in the API Packs list pages. To learn more about the Search feature, refer the topic: Search.
The search results page displays matches for the search from the following API Pack components:
API Pack name
Overview (all components)
Resource names in the pack
Resource description for each resource in the pack
Usage Plan names
Usage Plan - Associated Policy names
API Name
API Version number
Monetization strategy used
Plan documentation file name
Pack documentation file name
Pack branding details
To search components of an API Pack:
Navigate to the API Packs screen.
In the search box, type in the keyword(s) for starting a search on an API Pack or one of its components.
For example, a search for the word ‘call duration’ in the API packs screen returns:
Call Details Pack
Draft
Pack Name : Call Details Pack
Short Description : details of calls
Pack Description : details of calls
Resource name matched In api :Credit Balance~1.0~/CallDuration
Resource Desc matched In api :Credit Balance~1.0~get the call duration for calls made for a period
Resource Name Matched In Plan :Gold:/CallDuration
Next Steps
In the next section, you will learn to export and import API Packs.
in the row that has the Resource/Operation that you want to delete. A notification message displays. Click OK to remove the Resource/Operation from the Pack Contents list.
to assign a new policy to the Plan. The Plan Level - Select Existing Usage Policies dialog box displays.
next to the Resource/Operation name to attach an existing policy to the Resource/Operation. The Resource Level – Select Existing Usage policies (REST)/ Operation Level – Select Existing Usage policies (SOAP) dialog box displays.
.
to display the Resource level - Data Recording script /Operation level - Data Recording script dialog box.
to display the Usage Plan Action menu.
. The API Pack Action menu displays.
to display the search results.