ms-ai-architect/skills/ms-ai-engineering/references/api-management/developer-portal-ai-apis.md

# Developer Portal for AI API Discovery & Onboarding

**Last updated:** 2026-02
**Status:** GA
**Category:** API Management & AI Gateway

---

## Introduksjon

Azure API Managements Developer Portal er en automatisk generert, fullt tilpassbar nettside for API-dokumentasjon og selvbetjening. Nar organisasjoner eksponerer AI-modeller som API-er gjennom APIM, blir Developer Portal den sentrale plattformen der utviklere oppdager tilgjengelige AI-kapabiliteter, tester modeller interaktivt, administrerer API-nokler og overvaker eget forbruk. I tillegg tilbyr Azure API Center et komplementaert API-katalogverktoy.

For norsk offentlig sektor er en veladministrert Developer Portal viktig for a fremme gjenbruk av AI-tjenester pa tvers av etater og avdelinger. I samsvar med Digitaliseringsdirektoratets prinsipper om deling av data og tjenester, kan en offentlig tilgjengelig (eller intern) Developer Portal gi oversikt over tilgjengelige AI-API-er, redusere duplikering av arbeid og senke terskelen for a ta i bruk AI i nye prosjekter.

Developer Portal tilbyr ut av boksen: API-dokumentasjon med OpenAPI-spesifikasjoner, interaktiv testkonsoll, brukerregistrering og API-nokkelhondtering, samt bruksanalyse. Portalen kan tilpasses med egne stiler, innhold og branding -- og kan ogsa self-hostes for full kontroll.

---

## Portaltilpasning

### Tilpasningsomrader

| Omrade | Beskrivelse | Metode |
|--------|-------------|--------|
| Visuelt design | Farger, fonter, logo | Visual editor i Azure Portal |
| Sidelayout | Menyer, sideoppsett, widgets | Drag-and-drop editor |
| Egendefinert innhold | Sider, guider, FAQ | Markdown/HTML editor |
| Widgets | API-liste, testconsole, profil | Konfigurerbare widgets |
| Custom HTML/CSS | Full kontroll over utseende | Kode-editor |
| Self-hosting | Full kontroll, egen infrastruktur | Open-source kodebase |

### Tilpasse Developer Portal for AI-API-er

Opprett dedikerte sider for AI-kapabiliteter:

**Eksempel: AI API Landing Page**

```html
<!-- Custom page in Developer Portal -->
<div class="ai-api-overview">
    <h1>AI API Gateway</h1>
    <p>Velkommen til var AI API Gateway. Her finner du dokumentasjon,
       testverktoy og tilgang til AI-modeller.</p>

    <div class="ai-models-grid">
        <div class="model-card">
            <h3>GPT-4o Chat Completions</h3>
            <p>Generell chatbot og tekstgenerering</p>
            <ul>
                <li>Maks tokens: 128K kontekst</li>
                <li>Responstid: ~500ms</li>
                <li>Pris: Se lisensoversikt</li>
            </ul>
            <a href="/apis/chat-completions">Dokumentasjon</a>
        </div>

        <div class="model-card">
            <h3>GPT-4o Mini</h3>
            <p>Raskere og rimeligere for enklere oppgaver</p>
            <ul>
                <li>Maks tokens: 128K kontekst</li>
                <li>Responstid: ~200ms</li>
                <li>Pris: 90% rimeligere enn GPT-4o</li>
            </ul>
            <a href="/apis/chat-completions-mini">Dokumentasjon</a>
        </div>

        <div class="model-card">
            <h3>Embeddings API</h3>
            <p>Tekstembeddings for sok og analyse</p>
            <ul>
                <li>Modell: text-embedding-ada-002</li>
                <li>Dimensjoner: 1536</li>
            </ul>
            <a href="/apis/embeddings">Dokumentasjon</a>
        </div>
    </div>
</div>
```

### Branding for norsk offentlig sektor

```css
/* Custom CSS for public sector AI portal */
:root {
    --portal-primary: #003366;      /* Norwegian government blue */
    --portal-secondary: #C8102E;    /* Norwegian flag red */
    --portal-background: #F5F5F5;
    --portal-text: #333333;
    --portal-font: 'Source Sans Pro', sans-serif;
}

.navbar {
    background-color: var(--portal-primary);
}

.api-card {
    border-left: 4px solid var(--portal-primary);
    padding: 16px;
    margin-bottom: 12px;
    background: white;
    border-radius: 4px;
    box-shadow: 0 1px 3px rgba(0,0,0,0.12);
}
```

---

## API-dokumentasjon

### Best practices for AI API-dokumentasjon

| Seksjon | Innhold |
|---------|---------|
| Oversikt | Hva modellen kan, bruksomrader, begrensninger |
| Autentisering | API-nokkel, OAuth 2.0, Managed Identity |
| Endepunkter | URL-er, HTTP-metoder, parametere |
| Request/Response | JSON-schemaer med eksempler |
| Feilkoder | Standardiserte feilmeldinger |
| Rate limits | Tokens per minutt, foresporsler per minutt |
| Bruksretningslinjer | Ansvarlig bruk, innholdspolicy |
| Kodeeksempler | Python, C#, JavaScript, curl |

### Legge til kodeeksempler i portalen

OpenAPI-spesifikasjonen kan berikes med eksempler:

```yaml
paths:
  /chat/completions:
    post:
      operationId: createChatCompletion
      summary: Create a chat completion
      description: |
        Genererer et chat completion-svar basert pa meldingshistorikk.
        Stotter bade system-, bruker- og assistentmeldinger.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            examples:
              simple:
                summary: Enkel chatmelding
                value:
                  model: gpt-4o
                  messages:
                    - role: user
                      content: "Hva er Microsoft Foundry?"
                  max_tokens: 500
              withSystem:
                summary: Med systemprompt
                value:
                  model: gpt-4o
                  messages:
                    - role: system
                      content: "Du er en norsk AI-assistent for offentlig sektor."
                    - role: user
                      content: "Forklar Schrems II for meg."
                  max_tokens: 1000
                  temperature: 0.3
```

---

## Interaktiv testkonsoll

### Konfigurere testkonsoll for AI-API-er

Developer Portal inkluderer en interaktiv testkonsoll der utviklere kan:

1. Velge API-operasjon (f.eks. Chat Completions)
2. Fylle inn parametere og request body
3. Sende foresporselen direkte
4. Se response inkludert token-forbruk

### Tilpasse testkonsollen

For AI-API-er er det nyttig a pre-populere request body:

```json
{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "system",
      "content": "Du er en hjelpsom assistent."
    },
    {
      "role": "user",
      "content": "Skriv din melding her..."
    }
  ],
  "max_tokens": 500,
  "temperature": 0.7
}
```

**Merk:** Testkonsollen bruker automatisk `Ocp-Apim-Subscription-Key` fra brukerens all-access-abonnement. For AI-API-er bor man begrense token-forbruk i test via rate limit policy.

### Rate limiting for testkonsoll

```xml
<policies>
    <inbound>
        <base />
        <!-- Lower limits for test console requests -->
        <choose>
            <when condition="@(context.Request.Headers.GetValueOrDefault("Referer", "").Contains("developer"))">
                <rate-limit calls="10" renewal-period="60" />
                <set-header name="x-max-tokens-override" exists-action="override">
                    <value>200</value>
                </set-header>
            </when>
        </choose>
    </inbound>
</policies>
```

---

## API-nokkelhondtering

### Abonnementsmodell for AI-API-er

APIM bruker Products og Subscriptions for tilgangskontroll:

| Produkt | Tilgang | Rate Limit | Bruksomrade |
|---------|---------|-----------|-------------|
| AI-Sandbox | Fri registrering | 100 tokens/min | Testing og utforskning |
| AI-Standard | Godkjent | 10 000 tokens/min | Normal produksjon |
| AI-Premium | Manuell godkjenning | 100 000 tokens/min | Hoyvolum-applikasjoner |
| AI-Internal | Bare admin | Ubegrenset | Interne systemer |

### Bicep: Produktkonfigurasjon

```bicep
resource sandboxProduct 'Microsoft.ApiManagement/service/products@2023-09-01-preview' = {
  parent: apiManagement
  name: 'ai-sandbox'
  properties: {
    displayName: 'AI Sandbox'
    description: 'Fri tilgang til AI-API-er for testing. Begrenset til 100 tokens per minutt.'
    subscriptionRequired: true
    approvalRequired: false
    state: 'published'
    terms: 'Bruk kun til testing. Ikke send sensitiv informasjon.'
  }
}

resource standardProduct 'Microsoft.ApiManagement/service/products@2023-09-01-preview' = {
  parent: apiManagement
  name: 'ai-standard'
  properties: {
    displayName: 'AI Standard'
    description: 'Standard tilgang for godkjente applikasjoner. 10K tokens per minutt.'
    subscriptionRequired: true
    approvalRequired: true
    state: 'published'
    terms: 'Krever godkjenning. Folg retningslinjer for ansvarlig AI-bruk.'
  }
}

resource premiumProduct 'Microsoft.ApiManagement/service/products@2023-09-01-preview' = {
  parent: apiManagement
  name: 'ai-premium'
  properties: {
    displayName: 'AI Premium'
    description: 'Hoyvolum-tilgang for produksjonssystemer. 100K tokens per minutt.'
    subscriptionRequired: true
    approvalRequired: true
    state: 'published'
  }
}
```

### Brukerregistrering og selvbetjening

| Funksjon | Konfigurasjon |
|----------|--------------|
| Registrering | Azure AD / Microsoft Entra ID SSO |
| Abonnementsgodkjenning | Manuell for Standard og Premium |
| Automatisk nokkelrotasjon | Stottes via portal |
| Bruksdashboard | Innebygd per abonnement |
| Notifikasjoner | E-post ved godkjenning/avvisning |

---

## Selvbetjeningsarbeidsflyt for brukere

### Onboarding-prosess

```
1. Bruker besaker Developer Portal
2. Logger inn med Microsoft Entra ID (SSO)
3. Blar gjennom tilgjengelige AI-API-er
4. Velger produkt (Sandbox / Standard / Premium)
5. Oppretter abonnement
   - Sandbox: Umiddelbar tilgang
   - Standard/Premium: Venter pa godkjenning
6. Mottar API-nokkel (primaer + sekundaer)
7. Tester i interaktiv konsoll
8. Integrerer i applikasjon
```

### Konfigurasjon av Developer Portal-tilgang

```xml
<!-- Restrict developer portal access -->
<policies>
    <inbound>
        <base />
        <!-- Require Azure AD authentication -->
        <validate-azure-ad-token tenant-id="{{TenantId}}">
            <client-application-ids>
                <application-id>{{DevPortalAppId}}</application-id>
            </client-application-ids>
        </validate-azure-ad-token>
    </inbound>
</policies>
```

### Deaktivere offentlig registrering

For interne AI-portaler, deaktiver fri registrering og bruk Azure AD:

1. Ga til Developer Portal > Administrative interface
2. Under **Identities**, fjern "Username and Password"
3. Legg til "Azure Active Directory" som eneste identity provider
4. Under **Settings**, deaktiver "Enable sign-up"

---

## Azure API Center: Komplementaer katalog

For storre organisasjoner kan Azure API Center brukes sammen med APIM Developer Portal:

| Egenskap | Developer Portal | API Center |
|----------|-----------------|------------|
| Hovedformal | Selvbetjening og testing | Organisatorisk katalog |
| API-registrering | Fra APIM | Fra flere kilder |
| MCP-server-registrering | Nei | Ja |
| Governance-metadata | Begrenset | Omfattende |
| Synkronisering | -- | Automatisk fra APIM |
| Copilot Studio-connector | Nei | Ja |

---

## Referanser

- [Azure API Management Developer Portal overview](https://learn.microsoft.com/en-us/azure/api-management/developer-portal-overview) -- oversikt
- [Tutorial: Access and customize the developer portal](https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-developer-portal-customize) -- tilpasningsveiledning
- [AI gateway - Developer experience](https://learn.microsoft.com/en-us/azure/api-management/genai-gateway-capabilities#developer-experience) -- AI-spesifikk developer experience
- [What is Azure API Management?](https://learn.microsoft.com/en-us/azure/api-management/api-management-key-concepts) -- APIM-oversikt
- [Register and discover MCP servers in API Center](https://learn.microsoft.com/en-us/azure/api-center/register-discover-mcp-server) -- MCP i API Center
- [Synchronize APIs between API Management and API Center](https://learn.microsoft.com/en-us/azure/api-center/synchronize-api-management-apis) -- synkronisering
- [API Management subscriptions](https://learn.microsoft.com/en-us/azure/api-management/api-management-subscriptions) -- abonnementshondtering
- [Self-host the developer portal](https://learn.microsoft.com/en-us/azure/api-management/developer-portal-self-host) -- self-hosting

## For Cosmo

- **Bruk denne referansen** nar kunden onsker a gjore AI-API-er tilgjengelige for interne eller eksterne utviklere med selvbetjening, dokumentasjon og tilgangskontroll.
- For norsk offentlig sektor, anbefal alltid Microsoft Entra ID (Azure AD) som identity provider for Developer Portal -- unnga brukernavn/passord-registrering for bedre sikkerhet og sentral brukerstyring.
- Kombiner APIM Developer Portal med Azure API Center for storre organisasjoner som har API-er fra flere kilder (ikke bare APIM) -- API Center gir en organisatorisk oversikt.
- Anbefal en produkt-hierarki med Sandbox (fri tilgang, lav limit), Standard (godkjent, normal limit) og Premium (manuell godkjenning, hoy limit) for a gi kontrollert tilgang uten a bremse innovasjon.
- Developer Portal er tilgjengelig i Developer, Basic, Standard og Premium tiers -- ikke i Consumption tier. For v2-tiers (Basic v2, Standard v2, Premium v2) er portalen tilgjengelig i alle bortsett fra Basic v2.