[DX-1520] Add explanation to the use of catalogue and catalog (#5084)

* Add explanation to the use of catalogue and catalog * Update tyk-docs/content/tyk-apis/tyk-portal-api/portal-documentation.md * Update tyk-docs/content/tyk-portal-api.md * Update portal-documentation.md
TykTechnologies · Jul 16, 2024 · cf48485 · cf48485
1 parent 2e3c097
commit cf48485
Show file tree

Hide file tree

Showing 4 changed files with 52 additions and 40 deletions.
diff --git a/tyk-docs/content/tyk-apis/tyk-portal-api/portal-documentation.md b/tyk-docs/content/tyk-apis/tyk-portal-api/portal-documentation.md
@@ -1,12 +1,27 @@
 ---
 date: 2017-03-27T12:28:24+01:00
-title: Portal Documentation
-menu:
-  main:
-    parent: "Tyk Portal API"
-weight: 6
+title: API Publishing Endpoints
+description: "This page details the API endpoint used for publishing APIs to Tyk classic Dev Portal. API platform teams and API owners can use this endpoint to integrate their APIs, making them visible and accessible to developers."
+tags: ["Tyk Classic Portal API Publishing Endpoints", "Classic Portal API"]
 ---
-This section covers both [Documentation](#documentation) and [Catalog](#catalog) endpoints.
+This page describes the endpoints to create [catalog](#catalog) and [Swagger documentation](#documentation) for your API.
+
+</br>
+
+{{< note success >}}
+
+**Important Note on Spelling:**
+
+While our documentation now uses American English, the product itself, including UI, configuration fields, environment
+variables, and APIs endpoints, retain British English spellings. When interacting with the product, please continue
+using the British English spellings as they appear in the interface and API. (This means that for existing users nothing
+has changed).
+</br>
+**Example:** The API endpoint `/api/portal/catalogue` as shown throughout this page uses British spelling. In all other
+instances, such as when describing or referring to this object in the documentation, we will use the
+American spelling "catalog".
+
+{{< /note >}}
 
 ## Documentation
 
@@ -94,15 +109,15 @@ authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
 
 #### Sample Request
 
-```{.copyWrapper}
+```http
 GET /api/portal/catalogue HTTP/1.1
 Host: localhost
 authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
 ```
 
 #### Sample Response
 
-```
+```json
 {
   "id":"5cc03284d07e7f00019404b4",
   "org_id":"5cc03283d07e7f00019404b3",
@@ -252,15 +267,15 @@ authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
 
 #### Sample Request
 
-```{.copyWrapper}
+```http
 POST /api/portal/catalogue HTTP/1.1
 Host: localhost
 authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
 ```
 
 #### Sample Response
 
-```
+```yaml
 {
   Response here
 }
@@ -278,15 +293,15 @@ authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
 
 #### Sample Request
 
-```{.copyWrapper}
+```http
 PUT /api/portal/catalogue HTTP/1.1
 Host: localhost
 authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
 ```
 
 #### Sample Response
 
-```
+```yaml
 {
   Response here
 }

diff --git a/tyk-docs/content/tyk-apis/tyk-portal-api/portal-keys.md b/tyk-docs/content/tyk-apis/tyk-portal-api/portal-keys.md
@@ -21,15 +21,15 @@ aliases:
 
 #### Sample Request
 
-```{.copyWrapper}
+```http
 GET /api/portal/requests HTTP/1.1
 Host: localhost
 authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
 ```
 
 #### Sample Response
 
-```
+```json
 {
   "Data":[
     {
@@ -995,15 +995,15 @@ authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
 
 #### Sample Request
 
-```{.copyWrapper}
+```http
 GET /api/portal/requests/KEYID HTTP/1.1
 Host: localhost
 authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
 ```
 
 #### Sample Response
 
-```
+```json
 {
   "id":"5cf61bff0313b300010b89ac",
   "org_id":"5cc03283d07e7f00019404b3",
@@ -1208,7 +1208,7 @@ authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
 
 #### Sample Request
 
-```{.copyWrapper}
+```http
 POST /api/portal/requests HTTP/1.1
 Host: localhost
 authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
@@ -1372,7 +1372,7 @@ authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
 
 #### Sample Response
 
-```
+```json
 {
   "Status": "OK",
   "Message": "5efde61749960c000137f590",
@@ -1392,7 +1392,7 @@ authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
 
 #### Sample Request
 
-```{.copyWrapper}
+```http
 UPDATE /api/portal/requests/5efde61749960c000137f590 HTTP/1.1
 Host: localhost
 authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
@@ -1556,7 +1556,7 @@ authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
 
 #### Sample Response
 
-```
+```json
 {
   "Status": "OK",
   "Message": "5efde61749960c000137f590",
@@ -1576,15 +1576,15 @@ authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
 
 #### Sample Request
 
-```{.copyWrapper}
+```http
 DELETE /api/portal/requests/5efde61749960c000137f590 HTTP/1.1
 Host: localhost
 authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
 ```
 
 #### Sample Response
 
-```
+```json
 {
   "Status": "OK",
   "Message": "Data deleted",
@@ -1604,15 +1604,15 @@ authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
 
 #### Sample Request
 
-```{.copyWrapper}
+```http
 PUT /api/portal/requests HTTP/1.1
 Host: localhost
 authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
 ```
 
 #### Sample Response - Authentication Token
 
-```
+```json
 {
     "RawKey": "eyJvcmciOiI1ZTlkOTU0NGExZGNkNjAwMDFkMGVkMjAiLCJpZCI6ImQ0NzIzOWUxMjg3NTRjMGM5MTQ4MzYzMjg2YjhlZDQ2IiwiaCI6Im11cm11cjY0In0=",
     "Password": ""
@@ -1623,7 +1623,7 @@ authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
 
 #### Sample Response - Basic Authentication
 
-```
+```json
 {
     "RawKey": "ffeLySpZR5",
     "Password": "XJSm3gZIeDdk"

diff --git a/tyk-docs/content/tyk-portal-api.md b/tyk-docs/content/tyk-portal-api.md
@@ -1,13 +1,10 @@
 ---
-title: Tyk Portal API
-weight: 190
-menu:
-  main:
-    parent: "Tyk Portal Classic"
-weight: 8
+title: Classic Portal API
+description: "Landing page for the Tyk Classic Portal API documentation"
+tags: ["Tyk Classic Portal API", "Classic Portal API "]
 ---
 
-The Tyk Portal API covers all available endpoints for your developer portal, including:
+This section describes the Tyk Classic Portal API endpoints. It includes the following:
 
 * [Portal Keys]({{< ref "tyk-apis/tyk-portal-api/portal-keys" >}})
 * [Portal Policies]({{< ref "tyk-apis/tyk-dashboard-api/portal-policies" >}})

diff --git a/tyk-docs/data/menu.yaml b/tyk-docs/data/menu.yaml
@@ -3057,26 +3057,26 @@ menu:
           category: Directory
           show: True
           menu:
-          - title: "Portal Configuration"
+          - title: "Overview"
+            path: /tyk-portal-api
+            category: Page
+            show: True
+          - title: "Configuration"
             path: /tyk-apis/tyk-portal-api/portal-configuration
             category: Page
             show: True
-          - title: "Portal Developers"
+          - title: "Developers"
             path: /tyk-apis/tyk-portal-api/portal-developers
             category: Page
             show: True
-          - title: "Portal Documentation"
+          - title: "API Publishing"
             path: /tyk-apis/tyk-portal-api/portal-documentation
             category: Page
             show: True
-          - title: "Portal Keys"
+          - title: "Key Requests"
             path: /tyk-apis/tyk-portal-api/portal-keys
             category: Page
             show: True
-          - title: "Tyk Portal API"
-            path: /tyk-portal-api
-            category: Page
-            show: True
         - title: "Environment variables"
           category: Directory
           show: False