Bluestone API Integration Tutorial: Komplet udviklerguide med TypeScript

Hvad du vil lære

Denne tutorial guider dig gennem integration med Bluestone PIM API, fra initial autentificering til avanceret produktsøgningsfunktionalitet. Du vil bygge en komplet TypeScript applikation, der demonstrerer API-brugsmønstre fra den virkelige verden.

Bluestones MACH-certificerede API arkitektur giver kraftfulde søgekapabiliteter gennem Elasticsearch, omfattende autentificering via MAPI credentials og fleksible dataadgangsmønstre. Denne tutorial dækker både succesfulde integrationsmønstre og de tilladelsesbaserede begrænsninger, du måske støder på.

Tutorial Resultater

Autentificer med Bluestone MAPI credentials
Sæt TypeScript projekt op med auto-genereret SDK
Implementer produktsøgning ved hjælp af Elasticsearch API
Håndter autentifikationstokens og automatisk fornyelse
Byg genanvendelige API klientmønstre
Forstå API tilladelser og adgangsniveauer

Forudsætninger

Nødvendige Credentials

Før du starter, skal du sikre dig, at du har adgang til et Bluestone PIM testmiljø med følgende credentials:

MAPI Credentials Påkrævet

Organisationsnavn (f.eks. 'SANDBOX - POC')
Miljøbetegnelse (TEST/PRODUCTION)
PAPI-nøgle til API adgang
MAPI Client ID til OAuth2 autentificering
MAPI Client Secret til sikker tokengenerering

Udviklingsmiljø

Node.js 16+ med npm/yarn
TypeScript udviklingssetup
Kodeeditor med TypeScript support
Grundlæggende forståelse af REST API'er og OAuth2
Kendskab til async/await mønstre

Kom i gang

Trin 1: Initialiser dit projekt

Opret et nyt Node.js projekt og installer de nødvendige dependencies til TypeScript udvikling og Bluestone API integration.

Projekt Initialisering

Sæt et nyt TypeScript projekt op med påkrævede dependencies

bash

# Initialiser nyt Node.js projekt
npm init -y

# Installer Bluestone SDK ved hjælp af officiel generator
npx api install "@docs-api-test-bspim/v1-core#dzoga1clxllapfw" --yes

# Installer TypeScript udviklingsdependencies
npm install -D typescript @types/node ts-node

# Opret TypeScript konfiguration
echo '{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020", "DOM"],
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "baseUrl": "."
  },
  "include": ["src/**/*", ".api/**/*"],
  "exclude": ["node_modules", "dist"]
}' > tsconfig.json

# Opret source mappe
mkdir src

"Selvom denne tutorial fokuserer på TypeScript implementering, giver Bluestones API reference omfattende eksempler på tværs af 20+ programmeringssprog inklusive C#/.NET, Python, Java, PHP, Ruby og Go. De grundlæggende autentificerings- og API-mønstre forbliver konsistente uanset dit valgte sprog."

— Sivert Kjøller Bertelsen, API Integrationsspecialist

Trin 2: Implementer autentificering

Bluestone bruger OAuth2 client credentials flow til API autentificering. MAPI credentials genererer bearer tokens, der udløber efter 3600 sekunder (1 time).

Forståelse af Bluestone autentificering

Autentificeringsprocessen involverer at poste dine client credentials til identity provider endpoint for at modtage et bearer token. Dette token skal inkluderes i alle efterfølgende API requests som en Authorization header.

Autentificering Implementering

Komplet autentificeringsmodul med credential management og token håndtering

typescript

import docsApiTestBspim from '../.api/apis/docs-api-test-bspim';

// Bluestone API Credentials
const CREDENTIALS = {
  // Erstat med dine faktiske credentials
  clientId: 'your-client-id-here',
  clientSecret: 'your-client-secret-here',
  grantType: 'client_credentials'
};

async function authenticateWithBluestoneAPI() {
  try {
    console.log('🔐 Autentificerer med Bluestone API...');
    console.log('📍 Organisation: Din Organisation');
    console.log('🌍 Miljø: TEST');
    
    // Generer token ved hjælp af MAPI credentials
    const response = await docsApiTestBspim.generateToken({
      client_id: CREDENTIALS.clientId,
      client_secret: CREDENTIALS.clientSecret,
      grant_type: CREDENTIALS.grantType
    });

    console.log('✅ Autentificering succesfuld!');
    
    if (response.data && response.data.access_token) {
      console.log('🎟️  Access Token opnået');
      console.log('⏱️  Udløber om:', response.data.expires_in, 'sekunder');
      console.log('🏷️  Token Type:', response.data.token_type);
      
      return {
        accessToken: response.data.access_token,
        expiresIn: response.data.expires_in,
        tokenType: response.data.token_type
      };
    }
    
  } catch (error) {
    console.error('❌ Autentificering fejlede:', error);
    throw error;
  }
}

export default authenticateWithBluestoneAPI;
export { CREDENTIALS };

Trin 3: Byg API klient med token management

Opret en genanvendelig API klient, der håndterer autentificering, token validering og automatisk fornyelse. Dette mønster sikrer, at din applikation opretholder gyldig autentificering gennem hele dens livscyklus.

Nøglefunktioner

API klienten implementerer automatisk token validering, håndterer udløbne tokens ved at re-autentificere og giver en ren interface til at lave autentificerede requests til forskellige Bluestone API endpoints.

API Klient med Token Management

Genanvendelig API klient der håndterer autentificering og token livscyklus

typescript

import docsApiTestBspim from '../.api/apis/docs-api-test-bspim';
import authenticateWithBluestoneAPI from './authenticate';

interface AuthenticatedApiClient {
  accessToken: string;
  expiresIn: number;
  tokenType: string;
  authenticatedAt: Date;
}

class BluestoneApiClient {
  private client: AuthenticatedApiClient | null = null;

  async initialize(): Promise<void> {
    console.log('🚀 Initialiserer Bluestone API Klient...');
    
    const authInfo = await authenticateWithBluestoneAPI();
    
    if (authInfo && authInfo.accessToken && authInfo.expiresIn && authInfo.tokenType) {
      this.client = {
        accessToken: authInfo.accessToken,
        expiresIn: authInfo.expiresIn,
        tokenType: authInfo.tokenType,
        authenticatedAt: new Date()
      };
      
      // Konfigurer SDK'et med bearer token
      docsApiTestBspim.auth(authInfo.accessToken);
      
      console.log('✅ API Klient initialiseret og autentificeret!');
    } else {
      throw new Error('Fejlede med at autentificere med Bluestone API');
    }
  }

  isTokenValid(): boolean {
    if (!this.client) return false;
    
    const now = new Date();
    const elapsed = (now.getTime() - this.client.authenticatedAt.getTime()) / 1000;
    const isValid = elapsed < this.client.expiresIn;
    
    if (!isValid) {
      console.log('⚠️  Token er udløbet, re-autentificering påkrævet');
    }
    
    return isValid;
  }

  getTokenInfo(): AuthenticatedApiClient | null {
    return this.client;
  }

  displayStatus(): void {
    if (!this.client) {
      console.log('❌ API Klient ikke initialiseret');
      return;
    }

    const now = new Date();
    const elapsed = (now.getTime() - this.client.authenticatedAt.getTime()) / 1000;
    const remaining = this.client.expiresIn - elapsed;

    console.log('\n📊 Bluestone API Klient Status:');
    console.log(`🔑 Token Type: ${this.client.tokenType}`);
    console.log(`⏰ Autentificeret på: ${this.client.authenticatedAt.toISOString()}`);
    console.log(`⏱️  Tid tilbage: ${Math.max(0, Math.floor(remaining))} sekunder`);
    console.log(`✅ Token gyldig: ${this.isTokenValid() ? 'Ja' : 'Nej'}`);
  }
}

export default BluestoneApiClient;

Trin 4: Implementer produktsøgning

Bluestone giver kraftfulde produktsøgningskapabiliteter gennem Elasticsearch. Søge-API'et understøtter komplekse queries, filtrering, sortering og paginering - essentielt for at bygge robuste PIM integrationer.

Forståelse af Bluestone API Endpoints

Baseret på virkelige tests har forskellige API endpoints varierende tilladelseskrav. Elasticsearch søge-endpoint har typisk bredere adgang end detaljerede produktstyringsendpoints.

Produktsøgning Implementering

Komplet produktsøgningsklient med Elasticsearch support

typescript

import BluestoneApiClient from './api-client';

// Bluestone API URLs til forskellige services
const API_ENDPOINTS = {
  MANAGEMENT_API: 'https://api.test.bluestonepim.com',
  SEARCH_API: 'https://api.test.bluestonepim.com/search'
};

interface ElasticsearchQuery {
  query?: any;
  size?: number;
  from?: number;
  sort?: any[];
}

class ProductSearchClient extends BluestoneApiClient {
  
  /**
   * Søg efter produkter ved hjælp af Elasticsearch query
   */
  async searchProductsElasticsearch(elasticsearchQuery: ElasticsearchQuery): Promise<any> {
    await this.ensureAuthenticated();
    
    console.log('🔍 Søger produkter med Elasticsearch query:', elasticsearchQuery);

    try {
      const response = await this.makeAuthenticatedAPIRequest(
        `${API_ENDPOINTS.SEARCH_API}/products/search`,
        'POST',
        elasticsearchQuery
      );
      
      console.log('✅ Elasticsearch produktsøgning succesfuld!');
      return response;
      
    } catch (error) {
      console.error('❌ Elasticsearch produktsøgning fejlede:', error);
      throw error;
    }
  }

  /**
   * Sikr at vi har et gyldigt autentifikationstoken
   */
  protected async ensureAuthenticated(): Promise<void> {
    if (!this.isTokenValid()) {
      console.log('🔄 Re-autentificerer...');
      await this.initialize();
    }
  }

  /**
   * Lav et autentificeret HTTP request til Bluestone API
   */
  protected async makeAuthenticatedAPIRequest(
    url: string, 
    method: 'GET' | 'POST' | 'PUT' | 'DELETE' = 'GET',
    body?: any
  ): Promise<any> {
    const tokenInfo = this.getTokenInfo();
    
    if (!tokenInfo) {
      throw new Error('Intet autentifikationstoken tilgængeligt');
    }

    const headers: Record<string, string> = {
      'Authorization': `${tokenInfo.tokenType} ${tokenInfo.accessToken}`,
      'Content-Type': 'application/json'
    };

    const requestOptions: RequestInit = {
      method,
      headers
    };

    if (body && (method === 'POST' || method === 'PUT')) {
      requestOptions.body = JSON.stringify(body);
    }

    console.log(`📡 Laver ${method} request til: ${url}`);
    
    const response = await fetch(url, requestOptions);
    
    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(`HTTP ${response.status}: ${errorText}`);
    }

    return await response.json();
  }
}

export default ProductSearchClient;

Trin 5: Praktiske brugseksempler

Nu hvor du har de grundlæggende komponenter, lad os udforske praktiske eksempler på brug af Bluestone API til almindelige integrationsscenarier.

Komplette Brugseksempler

Praktiske eksempler der viser forskellige søgemønstre og query typer

typescript

import ProductSearchClient from './product-search';

async function demonstrateBluestoneAPI() {
  const client = new ProductSearchClient();
  
  try {
    // Initialiser og autentificer
    console.log('🚀 Initialiserer Bluestone API Klient...');
    await client.initialize();
    
    // Eksempel 1: Grundlæggende søgning efter alle produkter
    console.log('\n1️⃣ Grundlæggende Produktsøgning (Match All)');
    const allProducts = await client.searchProductsElasticsearch({
      query: { match_all: {} },
      size: 10
    });
    
    if (allProducts && allProducts.data) {
      console.log(`✅ Fandt ${allProducts.data.length} produkter:`);
      allProducts.data.forEach((product: any, index: number) => {
        console.log(`   ${index + 1}. ID: ${product.id}`);
      });
    }
    
    // Eksempel 2: Avanceret boolean query med filtre
    console.log('\n2️⃣ Avanceret Boolean Query');
    const advancedResults = await client.searchProductsElasticsearch({
      query: {
        bool: {
          must: [
            { exists: { field: "id" } }
          ]
        }
      },
      size: 5,
      sort: [{ "_id": { "order": "desc" } }]
    });
    
    console.log(`✅ Avanceret query returnerede ${advancedResults.data?.length || 0} produkter`);
    
    // Eksempel 3: Paginering eksempel
    console.log('\n3️⃣ Paginering Eksempel');
    const paginatedResults = await client.searchProductsElasticsearch({
      query: { match_all: {} },
      size: 2,
      from: 0  // Start fra første resultat
    });
    
    console.log(`📄 Side 1: ${paginatedResults.data?.length || 0} produkter`);
    
    // Vis autentificeringsstatus
    client.displayStatus();
    
  } catch (error) {
    console.error('💥 API demonstration fejlede:', error);
  }
}

// Kør demonstrationen
if (require.main === module) {
  demonstrateBluestoneAPI();
}

Package.json Scripts

Praktiske npm scripts til udvikling og test

json

{
  "name": "bluestone-api-integration",
  "version": "1.0.0",
  "scripts": {
    "build": "tsc",
    "authenticate": "ts-node src/authenticate.ts",
    "search": "ts-node src/product-search.ts",
    "demo": "ts-node src/demo.ts",
    "dev": "ts-node src/demo.ts"
  },
  "dependencies": {
    "@api/docs-api-test-bspim": "file:.api/apis/docs-api-test-bspim"
  },
  "devDependencies": {
    "@types/node": "^22.15.29",
    "ts-node": "^10.9.2",
    "typescript": "^5.8.3"
  }
}

Trin 6: Kør din integration

Med din kode på plads kan du nu teste forskellige aspekter af Bluestone API integrationen ved hjælp af praktiske npm scripts.

Tilgængelige Kommandoer

`npm run authenticate` - Test grundlæggende autentificering
`npm run search` - Kør produktsøgningseksempler
`npm run demo` - Fuld demonstration med flere eksempler
`npm run build` - Kompiler TypeScript til JavaScript
`npm run dev` - Udviklingstilstand med auto-restart

Forventede Resultater

Når din integration fungerer korrekt, bør du se output lignende dette eksempel, der demonstrerer succesfuld autentificering og produktopdagelse.

Forventet Konsol Output

Eksempel på succesfulde API integrationsresultater

bash

🚀 Initialiserer Bluestone API Klient...
🔐 Autentificerer med Bluestone API...
📍 Organisation: SANDBOX - POC
🌍 Miljø: TEST
✅ Autentificering succesfuld!
🎟️  Access Token opnået
⏱️  Udløber om: 3600 sekunder
🏷️  Token Type: Bearer
✅ API Klient initialiseret og autentificeret!

1️⃣ Grundlæggende Produktsøgning (Match All)
🔍 Søger produkter med Elasticsearch query: { query: { match_all: {} }, size: 10 }
📡 Laver POST request til: https://api.test.bluestonepim.com/search/products/search
✅ Elasticsearch produktsøgning succesfuld!
✅ Fandt 6 produkter:
   1. ID: 67f3c4e7bb442e4f88e45c32
   2. ID: 67f3c4a810f2da33a7c88766
   3. ID: 67f3c47c36016948acd8d0dd
   4. ID: 67f3ba1cbb442e4f88e45958
   5. ID: 67f3a654bb442e4f88e4590d
   6. ID: 67f3a5d636016948acd8cc4b

2️⃣ Avanceret Boolean Query
✅ Avanceret query returnerede 6 produkter

📊 Bluestone API Klient Status:
🔑 Token Type: Bearer
⏰ Autentificeret på: 2025-01-15T12:06:07.957Z
⏱️  Tid tilbage: 3599 sekunder
✅ Token gyldig: Ja

Avancerede Elasticsearch Queries

Bluestones søge-API understøtter den fulde Elasticsearch Query DSL, hvilket muliggør sofistikerede produktopdagelsesmønstre. Her er almindelige query mønstre til PIM integrationer.

Avancerede Elasticsearch Query Eksempler

Almindelige query mønstre til produktsøgning og filtrering

typescript

// Eksempel query mønstre til forskellige brugssager

// 1. Match alle produkter (grundlæggende listing)
const matchAllQuery = {
  query: { match_all: {} },
  size: 20,
  from: 0
};

// 2. Boolean query med existence filter
const existenceQuery = {
  query: {
    bool: {
      must: [
        { exists: { field: "id" } },
        { exists: { field: "name" } }
      ]
    }
  },
  size: 10
};

// 3. Sortering og paginering
const sortedQuery = {
  query: { match_all: {} },
  size: 5,
  from: 0,
  sort: [
    { "_id": { "order": "desc" } },
    { "createdAt": { "order": "desc" } }
  ]
};

// 4. Term filtrering (når du kender specifikke værdier)
const termQuery = {
  query: {
    bool: {
      must: [
        { term: { "status": "active" } },
        { term: { "type": "product" } }
      ]
    }
  }
};

// 5. Range queries (til datoer, numre)
const rangeQuery = {
  query: {
    bool: {
      must: [
        {
          range: {
            "createdAt": {
              "gte": "2024-01-01",
              "lte": "2024-12-31"
            }
          }
        }
      ]
    }
  }
};

// Brugseksempel:
// const results = await client.searchProductsElasticsearch(matchAllQuery);

Fejlfinding af Almindelige Problemer

Autentificeringsfejl

Hvis autentificering fejler, skal du verificere at dine MAPI credentials er korrekte og at din organisation har API adgang aktiveret. Client ID og secret skal præcist matche det som Bluestone support har givet.

403 Forbidden Fejl

Nogle API endpoints kræver højere tilladelsesniveauer end andre. Søge-endpoints fungerer typisk med grundlæggende MAPI credentials, mens produktstyringsendpoints kan kræve yderligere tilladelser. Dette er by design for sikkerhed.

Token Udløb

Bearer tokens udløber efter 3600 sekunder. API klienten håndterer automatisk token fornyelse, men hvis du implementerer custom logik, skal du sikre at du tjekker token gyldighed før du laver requests.

Netværksforbindelse

Sikr at dit udviklingsmiljø kan nå Bluestone test endpoints. Nogle virksomhedsnetværk kan blokere ekstern API adgang.

Almindelige Fejlkoder

401 Unauthorized - Ugyldige eller udløbne credentials
403 Forbidden - Utilstrækkelige tilladelser til endpoint
404 Not Found - Ugyldig endpoint URL eller ressource ikke fundet
429 Rate Limited - For mange requests (standard: 500/minut)
500 Internal Server Error - Bluestone service problem

Integration Best Practices

Fejlhåndtering

Implementer altid ordentlig fejlhåndtering for API kald. Netværksproblemer, rate limiting og tilladelsesændringer kan forekomme i produktionsmiljøer.

Token Management

Opbevar tokens sikkert og implementer automatisk fornyelse. Log aldrig bearer tokens i produktionsmiljøer da de giver fuld API adgang.

Rate Limiting

Respekter Bluestones rate limits (standard 500 requests/minut). Implementer exponential backoff for rate-limiterede requests og overvej at cache responses når det er passende.

Miljøstyring

Brug miljøvariabler til credentials og API endpoints. Commit aldrig API nøgler til version control.

Monitorering

Implementer logging og monitorering for API integrationer. Spor autentificeringssuccesrater, responstider og fejlfrekvenser.

Produktionsovervejelser

Brug miljøvariabler til følsomme credentials
Implementer ordentlig logging uden at eksponere tokens
Tilføj retry logik med exponential backoff
Monitorer API forbrug og fejlrater
Cache responses når det er passende for at reducere API kald
Brug HTTPS til al API kommunikation

Klar til produktion?

Denne tutorial dækker det grundlæggende i Bluestone API integration. Til produktionsimplementeringer kan du overveje at implementere avancerede funktioner som webhook håndtering, bulk operationer og omfattende fejlgendannelse.

Lær om Bluestone PIM

Næste Skridt

Udvid din integration

Med grundlaget på plads kan du udvide din integration til at inkludere yderligere Bluestone API kapabiliteter som dine tilladelser tillader.

Integrationsudvidelser

Implementer webhook handlers til real-time data sync
Tilføj support for bulk produktoperationer
Integrer med Bluestones workflow og task API'er
Byg asset management funktionalitet ved hjælp af DAM API
Tilføj support for kategori- og attributstyring
Implementer dataeksport og synkroniseringsworkflows

Produktionsparathed

Sæt ordentlig miljøkonfiguration op
Implementer omfattende fejlhåndtering og retry logik
Tilføj monitorering og alarmer for API fejl
Opret automatiserede tests for din integration
Dokumenter dine API brugsmønstre til teamviden
Planlæg skalering og rate limit management

Kilder (1)

[1]

Bluestone API Reference

Bluestone(2025)API Dokumentation

Hvad du vil lære

Tutorial Resultater

Forudsætninger

Nødvendige Credentials

MAPI Credentials Påkrævet

Udviklingsmiljø

Kom i gang

Trin 1: Initialiser dit projekt

Projekt Initialisering

Trin 2: Implementer autentificering

Forståelse af Bluestone autentificering

Autentificering Implementering

Trin 3: Byg API klient med token management

Nøglefunktioner

API Klient med Token Management

Trin 4: Implementer produktsøgning

Forståelse af Bluestone API Endpoints

Produktsøgning Implementering

Trin 5: Praktiske brugseksempler

Komplette Brugseksempler

Package.json Scripts

Trin 6: Kør din integration

Tilgængelige Kommandoer

Forventede Resultater

Forventet Konsol Output

Avancerede Elasticsearch Queries

Avancerede Elasticsearch Query Eksempler

Fejlfinding af Almindelige Problemer

Autentificeringsfejl

403 Forbidden Fejl

Token Udløb

Netværksforbindelse

Almindelige Fejlkoder

Integration Best Practices

Fejlhåndtering

Token Management

Rate Limiting

Miljøstyring

Monitorering

Produktionsovervejelser

Klar til produktion?

Næste Skridt

Udvid din integration

Integrationsudvidelser

Produktionsparathed

Kilder (1)

Relaterede Artikler

Klar til at Transformere Din Produktdatahåndtering?