Skip to content

Commit

Permalink
Merging to release-5.4: [DX-1437] catalogue --> catalog (PR 2) (#5054)
Browse files Browse the repository at this point in the history
[DX-1437] catalogue --> catalog (PR 2) (#5054)

* catalogue 2

---------

Co-authored-by: Yaara <yaara@tyk.io>
  • Loading branch information
buger and letzya authored Jul 11, 2024
1 parent 7991f2b commit 61f137a
Show file tree
Hide file tree
Showing 24 changed files with 57 additions and 57 deletions.
10 changes: 5 additions & 5 deletions tyk-docs/content/getting-started/key-concepts/api-catalogue.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
date: 2017-03-23T13:02:38Z
title: Portal API Catalogue
title: Portal API Catalog
menu:
main:
parent: "Key Concepts"
Expand All @@ -9,14 +9,14 @@ aliases:
- /concepts/api-catalogue/
---

The API Catalogue is part of the API Developer Portal of the Dashboard. It is the central place for you to manage which APIs your registered developers have access to.
The API Catalog is part of the API Developer Portal of the Dashboard. It is the central place for you to manage which APIs your registered developers have access to.

The API catalogue is completely separate from the regular API list section of the dashboard, as you may only wish to expose some of those APIs managed by Tyk to end users.
The API catalog is completely separate from the regular API list section of the dashboard, as you may only wish to expose some of those APIs managed by Tyk to end users.

API Catalogue entries are not actual directly tied to APIs in any way, they are connected to policies.
API Catalog entries are not actual directly tied to APIs in any way, they are connected to policies.

The reason for this is that policies can give access to a bundle of underlying APIs and therefore can represent a facade of services exposed as a single interface.

The concept of the API Catalogue is that you publish what you wish your external APIs to appear as. So, for example, if you have a widgets API that is composed of 4 microservices (i.e. `/comments`, `/pricing`, `/details`, and `/SKU`), which are managed as four separate APIs in your Dashboard, but combined under a single Security Policy (so one token can access all four APIs), then you may not wish to have your users know these are microservices, they are just endpoints in your widgets API.
The concept of the API Catalog is that you publish what you wish your external APIs to appear as. So, for example, if you have a widgets API that is composed of 4 microservices (i.e. `/comments`, `/pricing`, `/details`, and `/SKU`), which are managed as four separate APIs in your Dashboard, but combined under a single Security Policy (so one token can access all four APIs), then you may not wish to have your users know these are microservices, they are just endpoints in your widgets API.

This approach allows you to separate "management" from "consumption" using a simple CMS-based bundling approach.
8 changes: 4 additions & 4 deletions tyk-docs/content/getting-started/tutorials/publish-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ This is for the closed source [Tyk Developer Portal]({{< ref "tyk-developer-port
{{< tab_end >}}
{{< tab_start "Self-Managed" >}}

## Add an API and Swagger based Docs to your Portal Catalogue
## Add an API and Swagger based Docs to your Portal Catalog

Managing your portal is a key part of Tyk Dashboard, this tutorial helps you get started working with your portal and publishing your APIs to your developers.

Expand Down Expand Up @@ -65,15 +65,15 @@ Save the policy by clicking **Create**.

The API that you defined earlier is active and will work as you've seen in the previous tutorial, this time we want to use the Portal to generate a token for a named developer.

Not all APIs are visible to the Portal, only the ones you tell it about, so from the **Catalogue** menu, select **Add API** then:
Not all APIs are visible to the Portal, only the ones you tell it about, so from the **Catalog** menu, select **Add API** then:

1. Select your **Default** policy
2. Fill in the description fields
3. Ensure the **Enable this API** is selected

Save the API Catalogue entry by clicking **Update**.
Save the API Catalog entry by clicking **Update**.

{{< img src="/img/2.10/portal_confirmation_on_prem.png" alt="Catalogue Entry" >}}
{{< img src="/img/2.10/portal_confirmation_on_prem.png" alt="Catalog Entry" >}}

### Step 6: Set your Portal hostname

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Additionally you can now mix policies defined for the same API but having differ

#### Developer Portal Updates

Developers now can have multiple API keys, and subscribe to multiple catalogues with a single key. Go to the Portal settings and set `Enable subscribing to multiple APIs with single key` option to enable this new flow. When enabled, developers will see the new API generation user interface, which allows users to request access to multiple Catalogs of the **same type** with a single key.
Developers now can have multiple API keys, and subscribe to multiple catalogs with a single key. Go to the Portal settings and set `Enable subscribing to multiple APIs with single key` option to enable this new flow. When enabled, developers will see the new API generation user interface, which allows users to request access to multiple Catalogs of the **same type** with a single key.

From an implementation point of view, Developer objects now have a `Keys` attribute, which is the map where the key is a `key` and the value is an array of policy IDs. The `Subscriptions` field can be considered as deprecated, with retained backwards compatibility. We have added new set of Developer APIs to manage the keys, similar to the deprecated subscriptions APIs.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ In the below example, an API Provider offers two API Products (the Accounts API
Customers subscribed to the enterprise plan can use both APIs, offering a higher user limit. Conversely, customers subscribed to the Free plan (individual developers or hobbyists) only have visibility of the Payment API.

To achieve that, the API Provider uses two catalogs to implement their business model so that they can offer different experiences for different customer audiences. This section explains how to achieve that using the Tyk Enterprise Developer Portal.
{{< img src="/img/dashboard/portal-management/enterprise-portal/org-catalogue-product-relation.png" alt="Relationship between catalogues, API Products, plans, teams, and organisations" >}}
{{< img src="/img/dashboard/portal-management/enterprise-portal/org-catalogue-product-relation.png" alt="Relationship between catalogs, API Products, plans, teams, and organisations" >}}

## Create organisation and teams
The Tyk Enterprise Developer Portal uses Organisation and Catalogs to segment access to APIs and plans. Therefore, the first thing is to create an organisation for your customers. If you don't want to provision organisations manually, you can leverage the [Admin APIs]({{< ref "/product-stack/tyk-enterprise-developer-portal/api-documentation/tyk-edp-api.md" >}}) or enable the [self-service organisation registration]({{< ref "/tyk-stack/tyk-developer-portal/enterprise-developer-portal/managing-access/manage-api-consumer-organisations.md" >}}).
Expand Down Expand Up @@ -73,7 +73,7 @@ While it is possible to create multiple public catalogs, we do not advise doing
Finally, add plans and API Products to the created catalog so that the selected developer teams can view them.
{{< img src="/img/dashboard/portal-management/enterprise-portal/add-team-products-and-plans.png" alt="Add teams, products, and plans to the catalogue" >}}

You can achieve the same result by navigating to the **API Products** menu. Adding an API Product to a catalogue through the **Catalogs** and the **API Products** menus will produce the same result.
You can achieve the same result by navigating to the **API Products** menu. Adding an API Product to a catalog through the **Catalogs** and the **API Products** menus will produce the same result.
{{< img src="/img/dashboard/portal-management/enterprise-portal/publish-products-to-catalogues.png" alt="Adding a product to a catalogue through the API Products menu" >}}

{{< note >}}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ In this section, you will learn how to customise the visual appearance of API Pr
## Customize API Products
To customise the visual appearance of API Products:
1. Navigate to the **API Products** menu, select the product that you want to customise (the Payment API in example below). In this menu you can customise the following aspects of API Products:
- **Catalogue display name**: This is the name that will be displayed in the external catalog.
- **Catalog display name**: This is the name that will be displayed in the external catalog.
- **Featured API Product**: Tick this option for the API Product to appear on the home page under the **Featured products** section.
- **Description**: A short description about what this API Product is. It is displayed in the catalog and on the API Product page.
- **Content**: A long text description that appears on the API Product overview page, the rich text editor enables you to add more information about the API Product e.g. use cases, features, etc.
Expand All @@ -41,9 +41,9 @@ From that page you can also manage [OAuth2.0 settings]({{< ref "/tyk-stack/tyk-d

Customise plans
1. To customise visual appearance of plans, open the **Plans** menu and select the plan you want to customise. You can customise the following settings:
- **Catalogue display name**: The name of the catalog that will be displayed in the API Product page.
- **Catalog display name**: The name of the catalog that will be displayed in the API Product page.
- **Scope**: Scope for the [OAuth2.0 settings]({{< ref "/tyk-stack/tyk-developer-portal/enterprise-developer-portal/api-access/dynamic-client-registration.md" >}}). Please refer to the [OAuth2.0 documentation]({{< ref "/tyk-stack/tyk-developer-portal/enterprise-developer-portal/api-access/dynamic-client-registration" >}}) for further guidance.
- **Catalogs**: The catalogues in which this plan is available. Catalogs and organisation are [covered]({{< ref "/product-stack/tyk-enterprise-developer-portal/getting-started/create-orgs-and-catalogs" >}}) later within this getting started guide.
- **Catalogs**: The catalogs in which this plan is available. Catalogs and organisation are [covered]({{< ref "/product-stack/tyk-enterprise-developer-portal/getting-started/create-orgs-and-catalogs" >}}) later within this getting started guide.
- **Auto-approve settings for access requests**: Determines if access requests for this plan should be approved automatically.
- **Access request frequency**: Defines how often developers can request access to a specific plan. This way the admins can prevent developers from creating too many keys and abusing their automatically approved plans.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -84,11 +84,11 @@ Here is a potential set-up

{{< img src="img/dashboard/portal-management/enterprise-portal/portal-org-team-user-example.png" alt="A sample org set-up" >}}

### Catalogues
### Catalogs

Catalogues enable the publishing API products and plans based on visibility and access requirements. The catalogue can be set to public or private. As an admin you can customise the audience of a private catalogue at a team level, allowing you to create completely custom catalogues if needed.
Catalogs enable the publishing API products and plans based on visibility and access requirements. The catalog can be set to public or private. As an admin you can customise the audience of a private catalog at a team level, allowing you to create completely custom catalogs if needed.

Here’s an example of how you could set up catalogues for the users above:
Here’s an example of how you could set up catalogs for the users above:

{{< img src="img/dashboard/portal-management/enterprise-portal/portal-catalogue-sample-set-up.png" alt="A sample catalogue set-up" >}}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Additionally you can now mix policies defined for the same API but having differ

#### Developer Portal Updates

Developers now can have multiple API keys, and subscribe to multiple catalogues with a single key. Go to the Portal settings and set `Enable subscribing to multiple APIs with single key` option to enable this new flow. When enabled, developers will see the new API generation user interface, which allows users to request access to multiple Catalogs of the **same type** with a single key.
Developers now can have multiple API keys, and subscribe to multiple catalogs with a single key. Go to the Portal settings and set `Enable subscribing to multiple APIs with single key` option to enable this new flow. When enabled, developers will see the new API generation user interface, which allows users to request access to multiple Catalogs of the **same type** with a single key.

From an implementation point of view, Developer objects now have a `Keys` attribute, which is the map where the key is a `key` and the value is an array of policy IDs. The `Subscriptions` field can be considered as deprecated, with retained backwards compatibility. We have added new set of Developer APIs to manage the keys, similar to the deprecated subscriptions APIs.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ The main difference from the default template is two changes:
```

<details>
<summary><b>Click to expand and see the customised catalogue template</b></summary>
<summary><b>Click to expand and see the customised catalog template</b></summary>

```go-html-template
{{ define "cataloguePage" }} {{ $org_id := .OrgId}} {{ template "header" .}}
Expand All @@ -88,7 +88,7 @@ The main difference from the default template is two changes:
<!-- Main content here -->
<div class="container" style="margin-top:80px;">
<div class="row">
<h1>API Catalogue</h1>
<h1>API Catalog</h1>
</div>
{{ if .Error }}
<div class="row">
Expand Down Expand Up @@ -155,7 +155,7 @@ The main difference from the default template is two changes:
{{ else }}
<div class="row">
<p>
<em>It looks like there are no APIs in the Catalogue.</em>
<em>It looks like there are no APIs in the Catalog.</em>
</p>
</div>
{{ end }}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,7 @@ Take note of the `Key Hash` and `Key ID` as they will be needed later.

#### Publish the API to the Developer Portal

The API and the Facade API are now configured and can used to publish the API to the Tyk Developer Portal. Navigate to **Portal Management** &rarr; **Catalogue**, then click **Add New API**. Give it a public name, ex. `OAuth Facade API` and select the `facade-policy`.
The API and the Facade API are now configured and can used to publish the API to the Tyk Developer Portal. Navigate to **Portal Management** &rarr; **Catalog**, then click **Add New API**. Give it a public name, ex. `OAuth Facade API` and select the `facade-policy`.

{{< img src="/img/dcr/curity/7-split-curity-publish-api.png" alt="Publish API" >}}

Expand Down Expand Up @@ -247,7 +247,7 @@ Take note of the `Key Hash` and `Key ID` as they will be needed later.

#### Publish the API to the Developer Portal

The API is now configured and can be published to the Tyk Developer Portal. Navigate to **Portal Management** &rarr; **Catalogue**, then click **Add New API**. Give it a public name, ex. `Curity Demo API` and select the `Curity Policy`.
The API is now configured and can be published to the Tyk Developer Portal. Navigate to **Portal Management** &rarr; **Catalog**, then click **Add New API**. Give it a public name, ex. `Curity Demo API` and select the `Curity Policy`.

{{< img src="/img/dcr/curity/7-jwt-curity-publish-api.png" alt="Publish API" >}}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ The Portal supports a data structure to hold rudimentary menus, all pages have a
{{ range $index, $menuItem := .Menus.Main}}
<li><a href="/portal/{{$menuItem.URL}}">{{$menuItem.Title}}</a></li>
{{ end }}
<li><a href="/portal/apis/">API Catalogue</a></li>
<li><a href="/portal/apis/">API Catalog</a></li>
{{ if not .PortalConfig.DisableSignup }}
{{ if not .UserData }}
<li><a href="/portal/register/">Register</a></li>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,7 @@ If the user credentials are verified, the HTTP response code will be 200, otherw

### Listing Available APIs

Inside the admin dashboard in the portal menu, you can define **catalogues** with the list of APIs available to developers. Each defined API is identified by its policy id field.
Inside the admin dashboard in the portal menu, you can define **catalogs** with the list of APIs available to developers. Each defined API is identified by its policy id field.

#### Request

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ aliases:
- /tyk-developer-portal/customise/customise-documentation/
---

This short guide will show you how easy it is to swap out out the default https://swagger.io/tools/swagger-ui/ library for Portal Catalogue API documentation for another tool like [ReDoc](http://rebilly.github.io/ReDoc/)
This short guide will show you how easy it is to swap out out the default https://swagger.io/tools/swagger-ui/ library for Portal Catalog API documentation for another tool like [ReDoc](http://rebilly.github.io/ReDoc/)

* Open up the default `/opt/tyk-dashboard/portal/templates/swagger.html`

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ aliases:

Users that are signed up to your portal are called "Developers", these users have access to a Dashboard page which show them their API usage over the past 7 days as well as the policy and quota limits on their relevant keys.

Developers can sign up to multiple APIs using the API catalogue.
Developers can sign up to multiple APIs using the API catalog.

Developer accounts belong to an organisation ID, so accounts cannot be shared across organisations in a Tyk Dashboard setup.

Expand Down Expand Up @@ -69,7 +69,7 @@ Browse to the developers list view and select the developer that you wish to man

#### Step 2: View Keys List

This sections shows you the Keys and the policies connected to them. This view will always try to match the access level to a catalogue entry, if the policy assigned to a developer is not in the catalogue, the entry will read "(No Catalogue Entry)". We recommend that all policy levels are in your catalogue, even if they are not all live.
This sections shows you the Keys and the policies connected to them. This view will always try to match the access level to a catalog entry, if the policy assigned to a developer is not in the catalog, the entry will read "(No Catalog Entry)". We recommend that all policy levels are in your catalog, even if they are not all live.

#### Step 3: Click Options

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ After the policy is ready, switch back to the API settings and make sure that th

{{< img src="/img/dcr/gluu/step_6.png" alt="Step 6" >}}

Now you’re ready to add this API to the developer portal. Switch to the "Catalogue" section under "Portal Management" on the navigation menu. Click on "Add New API", set a name for it and select the newly created policy. For this example use "Gluu Policy":
Now you’re ready to add this API to the developer portal. Switch to the "Catalog" section under "Portal Management" on the navigation menu. Click on "Add New API", set a name for it and select the newly created policy. For this example use "Gluu Policy":

{{< img src="/img/dcr/gluu/step_7.png" alt="Step 7" >}}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,19 +25,19 @@ We have a YouTube walkthrough of how to publish a GraphQL API to your Developer

## How To Set Up

Simply create a GraphQL or Universal Data Graph API, create a Policy which protects it, and then publish it to the Developer Portal Catalogue.
Simply create a GraphQL or Universal Data Graph API, create a Policy which protects it, and then publish it to the Developer Portal Catalog.

In the "Create a Catalogue" section, at the bottom, make sure you enable the "Display Playground"
In the "Create a Catalog" section, at the bottom, make sure you enable the "Display Playground"


{{< img src="/img/portal/portal-graphql-setup.png" alt="Portal GraphQL Playground Setup" >}}

And then, when your API consumers are on the Developer Portal Catalogue and click on View Documentation, they will be taken to the GraphQL Playground.
And then, when your API consumers are on the Developer Portal Catalog and click on View Documentation, they will be taken to the GraphQL Playground.

{{< img src="/img/portal/portal-graphql-playground-viewdocs.png" alt="Portal GraphQL Playground View Docs" >}}


## Protected GraphQL Catalogue
## Protected GraphQL Catalog

If you have a protected API, your users won't be able to inspect the GraphQL schema or make API calls until they add their API Key to the Headers section:

Expand Down
Loading

0 comments on commit 61f137a

Please sign in to comment.