# Portal products in API Gateway Portal product A *portal product* represents a service or functionality that you want to share. Your portal product is a collection of product REST endpoints and product pages. *Product REST endpoints* are the access points to your portal product, and they consist of the path and method of a REST API and the stage it's deployed to. *Product pages* are documentation that you provide to explain how API consumers can use your product endpoints. A portal product can contain the entire `Prod` stage as a collection of product REST endpoints or just the `GET /pets` resource deployed to the `Prod` stage as a singular product REST endpoint. Your portal product is customizable. You can add custom documentation, rename the product REST endpoints, reorganize the display order, add new sections, and share products across Amazon accounts. In order for any changes you make to your portal product to take effect, you must republish any portals that use your portal product. ## Pet adoption portal product example As an example, you could have multiple REST APIs that represent a pet adoption service. You could use API Gateway to create a `pet adoption` portal product. This portal product would help customers discover which APIs they should use to meet and adopt pets. This portal product uses REST APIs that you already created, but it allows you to regroup and organize them. You can also provide documentation about the terms and conditions of using your pet adoption portal product and let customers try out your APIs. This information is all stored in your portal product. The following table shows three APIs that represent a pet adoption portal product, and their corresponding product REST endpoint operation names and page section names. | REST API ID | REST API path and method | REST API stage | Operation name | Page section | | --- | --- | --- | --- | --- | | kf5387miad | GET /dogs | Prod | View dogs | AdoptAnimals | | kf5387miad | GET /dogs/\$1dogId\$1 | Prod | View dog | AdoptAnimals | | ra8obxcevg | GET /cats | Prod | View cats | AdoptAnimals | | ra8obxcevg | GET /cats/\$1catId\$1 | Prod | View cat | AdoptAnimals | | h0rpx9cm62 | ANY /user/\$1userId\$1/\$1petId\$1\$1 | Beta | Request visit | AdoptProcess | In this example, two REST APIs, `ra8obxcevg` and `kf5387miad`, are grouped together in the `AdoptAnimals` section. The result of this ordering navigation would look like the following in a portal: Because the `ANY` method is a catch-all method, the portal shows all the supported HTTP methods. This portal also contains documentation that was created by the portal product owner. ## Next steps To get started with portal products, you can do the following: + To create a portal product, see [Create a portal product in API Gateway](apigateway-portals-create-portal-product.md). + To learn about the try it functionality, see [Enable try it for an API Gateway product REST endpoint in your portal](apigateway-portals-try-it.md). + To learn about product pages, see [Create a product page in API Gateway](apigateway-portals-create-product-page.md). + To learn about sharing your portal product, see [Share portal products in API Gateway](apigateway-portals-share-resources.md). After you create a portal product, you can publish it to a portal. For more information, see [Create a portal in API Gateway](apigateway-portals-create-portal.md). # Create a portal product in API Gateway Create a portal product The following procedure shows how to create a portal product. A portal is a collection of *portal products*. After you create your portal product, you create product REST endpoints and product pages. To learn about portal products, see [Portal products in API Gateway](apigateway-portals-portal-product.md). ## Considerations The following considerations might impact how you create a portal product: + Your portal product can contain both private and public REST APIs. Private APIs aren't supported for the try it functionality and, as a result, have a visual difference in your portal. As a portal owner, you might need to provide documentation to explain this. + If you create your portal product using the Amazon CLI or Amazon SDKs, your portal won't have any product endpoints or product pages. You need to add these resources using the Amazon CLI or console. To learn how to create a product REST endpoint, see [Create a product REST endpoint in API Gateway](apigateway-portals-create-product-rest-endpoint.md). To learn how to create a product page, see [Create a product page in API Gateway](apigateway-portals-create-product-page.md). ## Create a portal product The following procedure shows how to create a portal product. **To create a portal product** 1. Sign in to the API Gateway console at [https://console.amazonaws.cn/apigateway](https://console.amazonaws.cn/apigateway). 1. In the main navigation pane, choose **Portal products**. 1. Choose **Create product**. 1. For **Product name**, enter the name of your portal product. 1. For **Product description**, enter a description. 1. Choose **Next**. 1. To select your product REST endpoints, under **API endpoints** choose an API, and then choose a stage. 1. To add an endpoint to your product REST endpoints, select the API endpoint, and then choose **Add to product**. **Note** Do not choose **Next** without first choosing **Add to product**. The API endpoint will appear in the **Selected API endpoints** list. 1. Choose **Next**. 1. Review your selection and choose **Create product**. After you create your portal product using the console, all your product pages and product REST endpoint pages are drafts and won't appear in a portal. To have your product pages and product REST endpoint pages visible to consumers, you need to add your draft to a section. If you create your portal product using the Amazon CLI or Amazon SDKs, you add the draft to the section in the Amazon CLI command. Regardless of how you add your draft to a section, you must publish the portal that uses your portal products for it to be visible to consumers. **To add your draft to a page section** 1. Your drafts are listed in the **Documentation** tab. There are **Draft documentation pages** for your product pages and **Draft API reference pages** for your product REST endpoint pages. Choose **Draft API reference pages**. 1. Choose a draft API reference page. If you don't have any product REST endpoints, you won't have any draft API reference pages. To learn how to create a product REST endpoint, see [Create a product REST endpoint in API Gateway](apigateway-portals-create-product-rest-endpoint.md). 1. Choose **Edit page**. 1. On this page, you can overwrite any existing API documentation parts or use the API Gateway documentation. To allow the contents of your product REST endpoint page to be visible to consumers, under **Section name**, enter a name. If this was the `/pets-GET` endpoint, the page name could be `Pets`. 1. Choose **Save changes**. 1. The new page name you created appears under the **API reference pages** section. To allow the new page to be visible to consumers, you still need to republish your portal. For more information, see [Publish a portal in API Gateway](apigateway-portals-publish-portal.md). # Create a product REST endpoint in API Gateway Create a product REST endpoint A product REST endpoint is an access point to your portal product. Each endpoint consists of the path and method of a REST API and the stage it's deployed to. The endpoint includes any documentation you've defined for your REST API, or can be updated with custom documentation. When you create your product REST endpoint, you configure the following settings: + The product REST endpoint's operation name. If your REST API has the path and method `GET /pets`, in a portal, the name is `/pets`. Using the operation name, you can change the product REST endpoint name to `Pet summaries`. This doesn't impact your existing API. + The try it functionality for your product endpoint. This lets API consumers try your APIs in your portal. If you create a product endpoint for a private API, the try it functionality is set to `UNAVAILABLE`. For more information, see [Enable try it for an API Gateway product REST endpoint in your portal](apigateway-portals-try-it.md). + If you currently have documentation parts defined for your REST API, you can either import the documentation or override your existing documentation and create new product-level documentation using [GitHub Flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). Any documentation overrides do not propagate back to your API Gateway API documentation parts. If you import your current documentation parts, API Gateway syncs changes across your API to your product REST endpoint. ## Create a product REST endpoint The following procedure shows how to add a product REST endpoint to an existing portal product. To learn how to create a portal product and a product REST endpoint together, see [Create a portal product in API Gateway](apigateway-portals-create-portal-product.md). **To create a product REST endpoint for a product portal** 1. Sign in to the API Gateway console at [https://console.amazonaws.cn/apigateway](https://console.amazonaws.cn/apigateway). 1. In the main navigation pane, choose **Portal products**. 1. Choose a portal product. 1. Choose the **Associated endpoints** tab, and then choose **Add endpoints**. 1. To select your product REST endpoints, under **API endpoints** choose an API, and then choose a stage. 1. To add an endpoint to your product REST endpoints, select the API endpoint, and then choose **Add to product**. The API endpoint will appear in the **Selected API endpoints** list. 1. Choose **Submit**. 1. Your product REST endpoint page is now a draft. Choose **Draft API reference pages**, and then choose your product REST endpoint page to finalize the content of the page. 1. Choose **Edit page**. 1. To override the existing API Gateway documentation, for **Documentation source**, turn on **Override the documentation** and do the following: 1. For **Display content**, choose **Create override**. 1. For **Operation name**, enter a new operation name. 1. For **Page body**, enter your custom documentation. 1. (Optional) For **Endpoint**, enter a custom endpoint that appears in your portal. 1. To let customers invoke your API in your portal, select **Try it functionality**. For more information, see [Enable try it for an API Gateway product REST endpoint in your portal](apigateway-portals-try-it.md). 1. For **Section name**, enter a name or choose an existing section. When you add your product REST endpoint to a section, consumers can view your content on a published portal. 1. Choose **Save changes**. To allow the new page to be visible to consumers, you still need to republish your portal. For more information, see [Publish a portal in API Gateway](apigateway-portals-publish-portal.md). # Create a product page in API Gateway Create a product page A product page helps your product consumers understand and use your products. The documentation is at the product-level, so any portals that include your product have this documentation. API Gateway supports two types of product pages written in [GitHub Flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax): Overview page When you create your product, API Gateway automatically generates an **Overview** page for your product based on the information you provide when you create your product. This page has additional formatting that can't be changed. You can modify the text or remove the page from the portal product. Custom pages A custom page is a page written in Markdown. You might use this section for terms and conditions or a tutorial on how to use your product. You can change any custom page into an overview page. When you change a custom page into an overview page, the page content is formatted to match the overview page. ## Considerations The following considerations might impact your use of product pages: + This documentation is not at the API-level and doesn't include any methods, resources, or any request parameters. To learn how to modify the documentation at the API-level for a product, see [Update a product REST endpoint in API Gateway](apigateway-portals-update-product-endpoint.md). + You can't directly upload a `.md` file to your product. + You can modify the order of the product pages by modifying the page list in the display order of your portal product. For more information, see [Update a portal product in API Gateway](apigateway-portals-update-portal-product.md). + You need to republish any portals that include your product for documentation changes to take effect. + If you have multiple portals that use the same portal product, the product pages are the same across all portals. To have the same product REST endpoints but different product pages, create multiple products. ## Create a product page The following procedure shows how to create a product page. **To create a product page** 1. Sign in to the API Gateway console at [https://console.amazonaws.cn/apigateway](https://console.amazonaws.cn/apigateway). 1. In the main navigation pane, choose **Portal products**. 1. Choose a product. 1. Under **Documentation**, choose **Create custom page**. 1. For **Page title**, enter the page title. 1. For **Body**, enter your supplemental documentation using GitHub Flavored Markdown. The **Preview** section shows how your content appears in a portal. The final visual style might change based on your portal settings. 1. Choose **Create product page**. 1. Your product page is now a draft. Choose **Draft documentation pages**, and then choose your product page to finalize the content of the page. 1. Choose **Edit page**. 1. For **Section name**, enter a name or choose an existing section. When you add your product page to a section, consumers can view your content on a published portal. 1. Choose **Save changes**. To allow the new page to be visible to consumers, you still need to republish your portal. For more information, see [Publish a portal in API Gateway](apigateway-portals-publish-portal.md). # Update a portal product in API Gateway Update a portal product When you update a portal product, you can change the name, description, or the display order of how your product REST endpoints and product pages appear. To modify the display order, you modify the page list for product pages and the section name for product endpoints. If you do this using the Amazon CLI or SDKs, you specify the product page ARN or the product REST endpoint ARN. You need to republish any portals that use your products for your API consumers to see the changes reflected in a portal. ## Update a portal product The following procedure shows how to change the section list to reorder the product REST endpoints as they will appear in a portal. In this procedure, we assume you have at least two product REST endpoints in your portal product. **To update a portal product** 1. Sign in to the API Gateway console at [https://console.amazonaws.cn/apigateway](https://console.amazonaws.cn/apigateway). 1. In the main navigation pane, choose **Portal products**. 1. Choose a product. 1. In the **Documentation** tab, for **Product pages**, choose **Manage**. 1. Drag and drop the product REST endpoints to reorder them. You can also move product REST endpoints and product pages into the draft pages section. Pages in the draft pages are won't be visible in your portal. 1. (Optional) Rename the product REST endpoint names or add a new API reference section. These changes won't impact your REST APIs. 1. Choose **Save changes**. # Update a product REST endpoint in API Gateway Update a product REST endpoint When you update a product REST endpoint, you can change all the settings of the product endpoint except for the path and method of a REST API and the stage it's deployed to. Any changes to your product endpoints are updated automatically, but you need to republish any portals that use your products to see the changes reflected in a portal. ## Update a product REST endpoint The following procedure shows how to update a product REST endpoint to overwrite the current API documentation with custom API reference documentation. **To update a product REST endpoint** 1. Sign in to the API Gateway console at [https://console.amazonaws.cn/apigateway](https://console.amazonaws.cn/apigateway). 1. In the main navigation pane, choose **Portal products**. 1. Choose a product. 1. In the **Documentation** tab, under **API reference pages**, choose the name of a product REST endpoint, such as **/dogs - GET**. 1. For **Preview**, choose **Edit page**. 1. For **Documentation source**, turn on **Override the documentation**. 1. For **Display content**, choose **Override the existing content**. If you choose **Remove all content**, the content is removed from the page, but you can choose **Override the existing content** to access the documentation again. 1. In **Page body**, enter custom API reference documentation using [GitHub Flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). This documentation will not propagate back to API Gateway. 1. Choose **Save changes**. 1. You must republish any portals that use this portal product for the changes to take effect. # Update a product page in API Gateway Update product page When you update a product page, you can change all the settings of the product page. Any changes to your product page are updated automatically, but you need to republish any portals that use your products to see the changes reflected in a portal. # Share portal products in API Gateway Share portal products You can share a portal product across Amazon Web Services accounts using Amazon RAM. When you share a portal product, the other account can use your portal product in their own portal. With shared portal products, you can create a single catalog of your organization's APIs and enforce governance standards across your API ecosystem. At the same time, sharing portal products provides flexibility for API providers to develop, test, and maintain APIs in their own accounts. ## Considerations The following considerations might impact how you share portal resources: + When you share your product with another account, that account cannot modify any properties of your REST API. This includes the integration endpoints, the authorization strategy, or the stage configuration. + When you add another account's portal product into your portal, the portal product owner cannot view or control any other properties of your portal. The portal product owner only knows that the product is being used in your portal. + API Gateway portal products are shared at the Amazon Web Services Region level. + You can use one resource share with multiple principals, and after you create the resource share, you can add more principals to it. We recommend that when possible, you reuse your resource share. + If both accounts are in the same organization using Amazon Organizations, the resource share is automatically accepted. You still need to create the resource share using Amazon RAM. + If both accounts are in the same organization using Amazon Organizations and resource sharing within your organization is enabled, any principals in the organization that you share with are automatically granted access to the resource shares. There is no need for an invitation and you can skip the resource share. + If the account you shared the product with doesn't accept the resource share within **12 hours**, you must share the resource again. + After you create the resource share, Amazon RAM updates the product sharing policy of your product to prevent access to principals without explicit `allow` access. For more information, see [Determining whether a request is allowed or denied within an account](https://docs.amazonaws.cn//IAM/latest/UserGuide/reference_policies_evaluation-logic.html#policy-eval-denyallow) in the IAM User Guide. The updated resource policy will look like the following: ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "apigateway:GetProduct", "apigateway:ListEndpoints", "apigateway:ListPages", "apigateway:GetEndpoint", "apigateway:GetPage" ], "Resource": [ "arn:aws:apigateway:us-east-1:111122223333:/portalproducts/product-id", "arn:aws:apigateway:us-east-1:111122223333:/portalproducts/product-id/*" ] } ] } ``` Amazon RAM has prevented principals without explicit allow access to add your product to their portal, by adding the following: ``` "StringNotEquals": { "aws:PrincipalAccount": "555555555555" } ``` To learn how to share a product, see [Share your portal product with a portal owner in API Gateway](apigateway-portals-share-products.md). To learn how to add a product shared with you to your portal, see [Add a shared portal product to your portal in API Gateway](apigateway-portals-use-shared-products.md). # Share your portal product with a portal owner in API Gateway Share your portal product with a portal owner As a product owner, you can share your product with a portal owner in another Amazon Web Services account using Amazon RAM. You maintain full control of all product pages and product REST endpoint pages. ## Considerations The following considerations might impact how you share portal products: + You can share or unshare your portal products at any time. If you unshare a portal product while it's being used in a published portal, the portal owner won't be able to view the portal product, view any updates made to it, or republish or preview the portal until they remove the portal product. + You can view the portal products that you've shared with other accounts. + You can't modify any portals that contain your portal product, unless you create the portal yourself. ## Share your portal product The following procedure shows how to create a resource share. ------ #### [ Amazon Web Services Management Console ] To use the Amazon Web Services Management Console, see [Creating a resource share in Amazon RAM](https://docs.amazonaws.cn/ram/latest/userguide/working-with-sharing-create.html) in the *Amazon RAM User Guide*. For **Select resource type**, choose **API Gateway Product**. ------ #### [ Amazon CLI ] The following [create-resource-share](https://docs.amazonaws.cn/cli/latest/reference/ram/create-resource-share.html) creates a resource share for your private custom domain name. It can take a few minutes for the resource and principal associations to complete. For principals, provide an account ID or an Organizations ID, such as `arn:aws:organizations::123456789012:organization/o-1234abcd`. You can provide multiple principals for your resource share. ``` aws ram create-resource-share \ --region us-west-2 \ --name portal-product-resource-share \ --permission-arns arn:aws:ram::aws:permission/AWSRAMDefaultPermissionAPIGatewayDeveloperPortalProduct \ --resource-arns arn:aws:apigateway:us-west-2:111122223333:/portalproducts/p000000000 \ --principals 222222222222 ``` ------ To unshare your portal product, use Amazon RAM to delete the resource share. At any time, you can modify the product sharing policy to modify which principals can use your portal products in their portals. **To update the product sharing policy** 1. Sign in to the API Gateway console at [https://console.amazonaws.cn/apigateway](https://console.amazonaws.cn/apigateway). 1. In the main navigation pane, choose **Portal products**. 1. Choose a product. 1. In the **Product sharing** tab, for **Product sharing policy**, choose **Manage product sharing policy**. 1. If you haven't shared your product before, your product sharing policy will deny all access to other accounts to your portal products. You need to update the policy to allow access for certain accounts to your portal product. 1. After you have updated your product sharing policy, choose **Save changes**. # Add a shared portal product to your portal in API Gateway Add a shared portal product to your portal As a portal owner, you can use portal products shared with you by other accounts in your portal. You maintain full control of your portal. ## Considerations The following considerations might impact how you share portal resources: + You must accept the product resource share from the product owner to use their product in your portal. If you and the product owner are in the same Organizations, Amazon RAM can complete some sharing steps for you. + If the product owner unshares a product while it's in your published portal, the product will still be visible on the portal, but you won't be able to publish the portal again until you remove this product. It's your responsibility as the portal owner to remove the product from your portal, as the product owner can't do that for you. + You can view the portal products, the product pages, and the product REST endpoint pages, but you cannot modify any of these resources. + If a product is shared with you, you can't share it with another account. ## (Optional) Accept the resource share After your product owner creates a resource share, you have **12 hours** to accept it. If you are in the same organization using Amazon Organizations as the product owner, the share is automatically accepted. If you are in an organization that has automatic shared resources enabled, the resource is automatically shared with you. ------ #### [ Amazon Web Services Management Console ] To use the Amazon Web Services Management Console, see [Accepting and rejecting resource share invitations](https://docs.amazonaws.cn/ram/latest/userguide/working-with-shared-invitations.html) in the *Amazon RAM User Guide*. ------ #### [ Amazon CLI ] To find all the resources shared with you, use the following [get-resource-share-invitations](https://docs.amazonaws.cn/cli/latest/reference/ram/get-resource-share-invitations.html) command: ``` aws ram get-resource-share-invitations \ --region us-west-2 ``` Use the resulting resource share ARN to accept the resource share invitation. The following [accept-resource-share-invitation](https://docs.amazonaws.cn/cli/latest/reference/ram/accept-resource-share-invitation.html) command accepts the resource share. ``` aws ram accept-resource-share-invitation \ --resource-share-invitation-arn arn:aws:ram:us-west-2:123456789012:resource-share-invitation/1e3477be-4a95-46b4-bbe0-c4001EXAMPLE \ --region us-west-2 ``` ------ ## Add a shared product to your portal After you accept the resource share, you add the product to your portal. ------ #### [ Amazon Web Services Management Console ] **To add a shared product to your portal** 1. Sign in to the API Gateway console at [https://console.amazonaws.cn/apigateway](https://console.amazonaws.cn/apigateway). 1. In the main navigation pane, choose **Portals**. 1. Choose a portal. 1. In the **Products** tab, for **Portal products**, choose **Add products**. 1. Add a product to your portal. Shared products are shown as `shared` in the products list. 1. Choose **Save changes**. ------ #### [ Amazon CLI ] To find all the portal products shared with you, use the following `get-portal-products` command: ``` aws apigatewayv2 get-portal-products \ --resource-owner OTHER_ACCOUNTS \ --region us-west-2 ``` To add a shared portal product to your portal, use the following `update-portal` command: ``` aws apigateway update-portal \ --included-portal-product-arns arn:aws:apigateway:us-west-2:111122223333:/portalproducts/p000000000 \ --region us-west-2 ``` ------ # Enable try it for an API Gateway product REST endpoint in your portal Enable try it for a product REST endpoint in your portal Use try it to let an API consumer invoke your product endpoint from your portal. When an API consumer uses try it, they enter method request parameters and invoke your product endpoint. Then, API Gateway invokes your API over the public internet and returns the response in the try it window. You can use a custom product page to provide any additional information about required parameters to access your API. API Gateway uses the following limits to protect your APIs: + API Gateway only allows 3 requests per second to your API. + API Gateway uses a built-in timeout limit of 29000 ms. Your actual API might have a higher timeout limit, but API Gateway does not apply this timeout when a customer uses try it. + API Gateway limits the response payload to 6MB. ## Considerations The following considerations might impact how you use try it: + Try it is not supported when you preview a portal. + Try it is not supported for the REST APIs with the following features: + Private APIs + APIs that use mutual TLS + APIs that use private or self signed SSL certificates As the portal owner you are responsible for communicating with your API consumers the reasoning of the why try it button isn't there for any REST APIs that aren't supported. API Gateway does not explain this for you. ## Enable try it for a product REST endpoint The following procedure shows how to enable try it for a product endpoint. To learn how to use try it in a portal, see [Use an API Gateway portal](apigateway-portals-use-portal.md). **Enable try it for a product REST endpoint** 1. In the main navigation pane, choose **Portal products**. 1. Choose a product. 1. In the **Documentation** tab, under **API reference pages**, choose the name of a product REST endpoint, such as **/dogs - GET**. 1. Choose **Edit page**. 1. To let customers invoke your API in your portal, select **Try it functionality**. 1. Choose **Save changes**. 1. You must republish any portals that use this portal product for the changes to take effect. # Delete a portal product in API Gateway Delete a portal product When you delete a portal product, it cannot be recovered. ## Delete a portal product The following procedure shows how to delete a portal product. **To delete a portal product** 1. Sign in to the API Gateway console at [https://console.amazonaws.cn/apigateway](https://console.amazonaws.cn/apigateway). 1. In the main navigation pane, choose **Portal products**. 1. Choose a portal product. 1. Choose **Delete**. 1. Confirm your choice and choose **Delete**. 1. You must republish any portals that use this portal product for the changes to take effect.