Skip to content

refactor: centralize API slug mapping into a single file #903

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

refactor: centralize API slug mapping into a single file #903

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fef7a53
refactor: centralize API slug mapping into a single file
brunoamui Mar 14, 2025
014de6f
Merge branch 'main' into sync-api-reference-mapping
brunoamui Mar 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
- [Directory Tree](#directory-tree)
- [React Preferences](#react-preferences)
- [Code Linting and Format](#code-linting-and-format)
- [API Slug Mapping](#api-slug-mapping)
- [Commits](#commits)
- [How to make a commit](#how-to-make-a-commit)
- [Branches](#branches)
Expand Down Expand Up @@ -213,6 +214,31 @@ flowchart TB

You might want to configure ESLint and Prettier in your code editor to see errors and correction suggestions at development time.

### API Slug Mapping

The mapping between API display names and their corresponding slugs is centralized in a single file to make maintenance easier:

```
src/utils/api-slug-mapping.ts
```

This mapping is used in various parts of the application:

1. In `getReferencePaths.ts` to generate paths for API reference documentation
2. In `api/openapi/[slug].tsx` to handle OpenAPI schema requests
3. In `api/postman/[slug].tsx` to handle Postman collection requests

When adding a new API or modifying an existing one, you should update only this file, and all parts of the system that use this mapping will automatically get the updated information.

Example:
```typescript
// src/utils/api-slug-mapping.ts
export const apiSlugMap: { [key: string]: string } = {
'VTEX - New API': 'new-api-slug',
// ... other mappings
}
```

### Commits

By simplicity, we have three types of commits:
Expand Down
60 changes: 3 additions & 57 deletions src/pages/api/openapi/[slug].tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,63 +4,9 @@ export const config = {
},
}

const referencePaths = objectFlip({
'VTEX - Antifraud Provider API': 'antifraud-provider-protocol',
'VTEX - Legacy CMS Portal API': 'legacy-cms-portal-api',
'VTEX - Catalog API Seller Portal': 'catalog-api-seller-portal',
'VTEX - Catalog API': 'catalog-api',
'VTEX - Checkout API': 'checkout-api',
'VTEX - Checkout Configuration API': 'checkout-configuration-api',
'VTEX - Customer Credit API': 'customer-credit-api',
'VTEX - GiftCard Hub API': 'giftcard-hub-api',
'VTEX - Giftcard API': 'giftcard-api',
'VTEX - Giftcard Provider Protocol': 'giftcard-provider-protocol',
'VTEX - Headless CMS API': 'headless-cms-api',
'VTEX - Intelligent Search API': 'intelligent-search-api',
'VTEX - License Manager API': 'license-manager-api',
'VTEX - Logistics API': 'logistics-api',
'VTEX - Marketplace APIs': 'marketplace-apis',
'VTEX - Marketplace APIs - Suggestions': 'marketplace-apis-suggestions',
'VTEX - Marketplace APIs - Sent Offers': 'marketplace-apis-offer-management',
'VTEX - Marketplace Protocol - External Marketplace Mapper':
'marketplace-protocol-external-marketplace-mapper',
'VTEX - Marketplace Protocol - External Marketplace Orders':
'marketplace-protocol-external-marketplace-orders',
'VTEX - Marketplace Protocol - External Seller Fulfillment':
'marketplace-protocol-external-seller-fulfillment',
'VTEX - Marketplace Protocol - External Seller Marketplace':
'marketplace-protocol',
'VTEX - Master Data API - v2': 'master-data-api-v2',
'VTEX - MasterData API - v10.2': 'masterdata-api',
'VTEX - Message Center API': 'message-center-api',
'VTEX - Orders API PII version': 'orders-api-pii-version',
'VTEX - Orders API': 'orders-api',
'VTEX - Payment Provider Protocol': 'payment-provider-protocol',
'VTEX - Payments Gateway API': 'payments-gateway-api',
'VTEX - Pick and Pack Last Mile Protocol API': 'pick-and-pack-protocol-api',
'VTEX - Pick and Pack Order Changes API': 'pick-and-pack-order-changes-api',
'VTEX - Policies System API': 'policies-system-api',
'VTEX - Pricing API': 'pricing-api',
'VTEX - Pricing Hub': 'pricing-hub',
'VTEX - Profile System': 'profile-system',
'VTEX - Promotions & Taxes API': 'promotions-and-taxes-api',
'VTEX - Reviews and Ratings API': 'reviews-and-ratings-api',
'VTEX - SKU Bindings API': 'sku-bindings-api',
'VTEX - Search API': 'search-api',
'VTEX - Session Manager API': 'session-manager-api',
'VTEX - Subscriptions API v3': 'subscriptions-api-v3',
'VTEX - Tracking': 'tracking',
'VTEX - VTEX Do API': 'vtex-do-api',
'VTEX - VTEX ID API': 'vtex-id-api',
'VTEX - VTEX Shipping Network API': 'vtex-shipping-network-api',
'VTEX - Promotions & Taxes API - v2': 'promotions-and-taxes-api-v2',
'VTEX - Intelligent Search Events API - Headless':
'intelligent-search-events-api-headless',
'VTEX - Data Subject Rights': 'data-subject-rights-api',
'VTEX - Buyer Organizations': 'buyer-organizations',
'VTEX - Audience API': 'audience-api',
'VTEX - Ad Network API': 'vtex-ad-network-api',
})
import { apiSlugMap } from 'utils/api-slug-mapping'

const referencePaths = objectFlip(apiSlugMap)

function objectFlip(obj: { [x: string]: string }) {
return Object.keys(obj).reduce((ret, key) => {
Expand Down
60 changes: 3 additions & 57 deletions src/pages/api/postman/[slug].tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,63 +4,9 @@ export const config = {
},
}

const referencePaths = objectFlip({
'VTEX - Antifraud Provider API': 'antifraud-provider-protocol',
'VTEX - Legacy CMS Portal API': 'legacy-cms-portal-api',
'VTEX - Catalog API Seller Portal': 'catalog-api-seller-portal',
'VTEX - Catalog API': 'catalog-api',
'VTEX - Checkout API': 'checkout-api',
'VTEX - Checkout Configuration API': 'checkout-configuration-api',
'VTEX - Customer Credit API': 'customer-credit-api',
'VTEX - GiftCard Hub API': 'giftcard-hub-api',
'VTEX - Giftcard API': 'giftcard-api',
'VTEX - Giftcard Provider Protocol': 'giftcard-provider-protocol',
'VTEX - Headless CMS API': 'headless-cms-api',
'VTEX - Intelligent Search API': 'intelligent-search-api',
'VTEX - License Manager API': 'license-manager-api',
'VTEX - Logistics API': 'logistics-api',
'VTEX - Marketplace APIs': 'marketplace-apis',
'VTEX - Marketplace APIs - Suggestions': 'marketplace-apis-suggestions',
'VTEX - Marketplace APIs - Sent Offers': 'marketplace-apis-offer-management',
'VTEX - Marketplace Protocol - External Marketplace Mapper':
'marketplace-protocol-external-marketplace-mapper',
'VTEX - Marketplace Protocol - External Marketplace Orders':
'marketplace-protocol-external-marketplace-orders',
'VTEX - Marketplace Protocol - External Seller Fulfillment':
'marketplace-protocol-external-seller-fulfillment',
'VTEX - Marketplace Protocol - External Seller Marketplace':
'marketplace-protocol',
'VTEX - Master Data API - v2': 'master-data-api-v2',
'VTEX - MasterData API - v10.2': 'masterdata-api',
'VTEX - Message Center API': 'message-center-api',
'VTEX - Orders API PII version': 'orders-api-pii-version',
'VTEX - Orders API': 'orders-api',
'VTEX - Payment Provider Protocol': 'payment-provider-protocol',
'VTEX - Payments Gateway API': 'payments-gateway-api',
'VTEX - Pick and Pack Last Mile Protocol API': 'pick-and-pack-protocol-api',
'VTEX - Pick and Pack Order Changes API': 'pick-and-pack-order-changes-api',
'VTEX - Policies System API': 'policies-system-api',
'VTEX - Pricing API': 'pricing-api',
'VTEX - Pricing Hub': 'pricing-hub',
'VTEX - Profile System': 'profile-system',
'VTEX - Promotions & Taxes API': 'promotions-and-taxes-api',
'VTEX - Reviews and Ratings API': 'reviews-and-ratings-api',
'VTEX - SKU Bindings API': 'sku-bindings-api',
'VTEX - Search API': 'search-api',
'VTEX - Session Manager API': 'session-manager-api',
'VTEX - Subscriptions API v3': 'subscriptions-api-v3',
'VTEX - Tracking': 'tracking',
'VTEX - VTEX Do API': 'vtex-do-api',
'VTEX - VTEX ID API': 'vtex-id-api',
'VTEX - VTEX Shipping Network API': 'vtex-shipping-network-api',
'VTEX - Promotions & Taxes API - v2': 'promotions-and-taxes-api-v2',
'VTEX - Intelligent Search Events API - Headless':
'intelligent-search-events-api-headless',
'VTEX - Data Subject Rights': 'data-subject-rights-api',
'VTEX - Buyer Organizations': 'buyer-organizations',
'VTEX - Audience API': 'audience-api',
'VTEX - Ad Network API': 'vtex-ad-network-api',
})
import { apiSlugMap } from 'utils/api-slug-mapping'

const referencePaths = objectFlip(apiSlugMap)

function objectFlip(obj: { [x: string]: string }) {
return Object.keys(obj).reduce((ret, key) => {
Expand Down
62 changes: 62 additions & 0 deletions src/utils/api-slug-mapping.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
/**
* Maps API display names to their corresponding slugs
* This mapping is used for generating reference documentation paths
*/

export const apiSlugMap: { [key: string]: string } = {
'VTEX - Antifraud Provider API': 'antifraud-provider-protocol',
'VTEX - Legacy CMS Portal API': 'legacy-cms-portal-api',
'VTEX - Catalog API Seller Portal': 'catalog-api-seller-portal',
'VTEX - Catalog API': 'catalog-api',
'VTEX - Checkout API': 'checkout-api',
'VTEX - Checkout Configuration API': 'checkout-configuration-api',
'VTEX - Customer Credit API': 'customer-credit-api',
'VTEX - GiftCard Hub API': 'giftcard-hub-api',
'VTEX - Giftcard API': 'giftcard-api',
'VTEX - Giftcard Provider Protocol': 'giftcard-provider-protocol',
'VTEX - Headless CMS API': 'headless-cms-api',
'VTEX - Intelligent Search API': 'intelligent-search-api',
'VTEX - License Manager API': 'license-manager-api',
'VTEX - Logistics API': 'logistics-api',
'VTEX - Marketplace APIs': 'marketplace-apis',
'VTEX - Marketplace APIs - Suggestions': 'marketplace-apis-suggestions',
'VTEX - Marketplace APIs - Sent Offers': 'marketplace-apis-offer-management',
'VTEX - Marketplace Protocol - External Marketplace Mapper':
'marketplace-protocol-external-marketplace-mapper',
'VTEX - Marketplace Protocol - External Marketplace Orders':
'marketplace-protocol-external-marketplace-orders',
'VTEX - Marketplace Protocol - External Seller Fulfillment':
'marketplace-protocol-external-seller-fulfillment',
'VTEX - Marketplace Protocol - External Seller Marketplace':
'marketplace-protocol',
'VTEX - Master Data API - v2': 'master-data-api-v2',
'VTEX - MasterData API - v10.2': 'masterdata-api',
'VTEX - Message Center API': 'message-center-api',
'VTEX - Orders API PII version': 'orders-api-pii-version',
'VTEX - Orders API': 'orders-api',
'VTEX - Payment Provider Protocol': 'payment-provider-protocol',
'VTEX - Payments Gateway API': 'payments-gateway-api',
'VTEX - Pick and Pack Last Mile Protocol API': 'pick-and-pack-protocol-api',
'VTEX - Pick and Pack Order Changes API': 'pick-and-pack-order-changes-api',
'VTEX - Policies System API': 'policies-system-api',
'VTEX - Pricing API': 'pricing-api',
'VTEX - Pricing Hub': 'pricing-hub',
'VTEX - Profile System': 'profile-system',
'VTEX - Promotions & Taxes API': 'promotions-and-taxes-api',
'VTEX - Reviews and Ratings API': 'reviews-and-ratings-api',
'VTEX - SKU Bindings API': 'sku-bindings-api',
'VTEX - Search API': 'search-api',
'VTEX - Session Manager API': 'session-manager-api',
'VTEX - Subscriptions API v3': 'subscriptions-api-v3',
'VTEX - Tracking': 'tracking',
'VTEX - VTEX Do API': 'vtex-do-api',
'VTEX - VTEX ID API': 'vtex-id-api',
'VTEX - VTEX Shipping Network API': 'vtex-shipping-network-api',
'VTEX - Promotions & Taxes API - v2': 'promotions-and-taxes-api-v2',
'VTEX - Intelligent Search Events API - Headless':
'intelligent-search-events-api-headless',
'VTEX - Data Subject Rights': 'data-subject-rights-api',
'VTEX - Buyer Organizations': 'buyer-organizations',
'VTEX - Audience API': 'audience-api',
'VTEX - Ad Network API': 'vtex-ad-network-api',
}
61 changes: 2 additions & 59 deletions src/utils/getReferencePaths.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,64 +4,7 @@ const referencePaths: { [slug: string]: string } = {}
import { getGithubTree } from './github-utils'
import { getLogger } from './logging/log-util'
import { githubConfig } from './github-config'

const fileSlugMap: { [key: string]: string } = {
'VTEX - Antifraud Provider API': 'antifraud-provider-protocol',
'VTEX - Legacy CMS Portal API': 'legacy-cms-portal-api',
'VTEX - Catalog API Seller Portal': 'catalog-api-seller-portal',
'VTEX - Catalog API': 'catalog-api',
'VTEX - Checkout API': 'checkout-api',
'VTEX - Checkout Configuration API': 'checkout-configuration-api',
'VTEX - Customer Credit API': 'customer-credit-api',
'VTEX - GiftCard Hub API': 'giftcard-hub-api',
'VTEX - Giftcard API': 'giftcard-api',
'VTEX - Giftcard Provider Protocol': 'giftcard-provider-protocol',
'VTEX - Headless CMS API': 'headless-cms-api',
'VTEX - Intelligent Search API': 'intelligent-search-api',
'VTEX - License Manager API': 'license-manager-api',
'VTEX - Logistics API': 'logistics-api',
'VTEX - Marketplace APIs': 'marketplace-apis',
'VTEX - Marketplace APIs - Suggestions': 'marketplace-apis-suggestions',
'VTEX - Marketplace APIs - Sent Offers': 'marketplace-apis-offer-management',
'VTEX - Marketplace Protocol - External Marketplace Mapper':
'marketplace-protocol-external-marketplace-mapper',
'VTEX - Marketplace Protocol - External Marketplace Orders':
'marketplace-protocol-external-marketplace-orders',
'VTEX - Marketplace Protocol - External Seller Fulfillment':
'marketplace-protocol-external-seller-fulfillment',
'VTEX - Marketplace Protocol - External Seller Marketplace':
'marketplace-protocol',
'VTEX - Master Data API - v2': 'master-data-api-v2',
'VTEX - MasterData API - v10.2': 'masterdata-api',
'VTEX - Message Center API': 'message-center-api',
'VTEX - Orders API PII version': 'orders-api-pii-version',
'VTEX - Orders API': 'orders-api',
'VTEX - Payment Provider Protocol': 'payment-provider-protocol',
'VTEX - Payments Gateway API': 'payments-gateway-api',
'VTEX - Pick and Pack Last Mile Protocol API': 'pick-and-pack-protocol-api',
'VTEX - Pick and Pack Order Changes API': 'pick-and-pack-order-changes-api',
'VTEX - Policies System API': 'policies-system-api',
'VTEX - Pricing API': 'pricing-api',
'VTEX - Pricing Hub': 'pricing-hub',
'VTEX - Profile System': 'profile-system',
'VTEX - Promotions & Taxes API': 'promotions-and-taxes-api',
'VTEX - Reviews and Ratings API': 'reviews-and-ratings-api',
'VTEX - SKU Bindings API': 'sku-bindings-api',
'VTEX - Search API': 'search-api',
'VTEX - Session Manager API': 'session-manager-api',
'VTEX - Subscriptions API v3': 'subscriptions-api-v3',
'VTEX - Tracking': 'tracking',
'VTEX - VTEX Do API': 'vtex-do-api',
'VTEX - VTEX ID API': 'vtex-id-api',
'VTEX - VTEX Shipping Network API': 'vtex-shipping-network-api',
'VTEX - Promotions & Taxes API - v2': 'promotions-and-taxes-api-v2',
'VTEX - Intelligent Search Events API - Headless':
'intelligent-search-events-api-headless',
'VTEX - Data Subject Rights': 'data-subject-rights-api',
'VTEX - Buyer Organizations': 'buyer-organizations',
'VTEX - Audience API': 'audience-api',
'VTEX - Ad Network API': 'vtex-ad-network-api',
}
import { apiSlugMap } from './api-slug-mapping'

export default async function getReferencePaths(
branch: string = githubConfig.openapiBranch
Expand All @@ -87,7 +30,7 @@ export default async function getReferencePaths(
: ''
if (filetype === 'json' || filetype === 'yaml') {
referencePaths[
fileSlugMap[filename] || filename
apiSlugMap[filename] || filename
] = `https://cdn.jsdelivr.net/gh/vtex/openapi-schemas/${path}`
}
}
Expand Down
Loading