api-portal-design

What this skill does

# API Portal Design Skill

## When to Use This Skill

Use this skill when:

- **Api Portal Design tasks** - Working on api documentation and developer portal design
- **Planning or design** - Need guidance on Api Portal Design approaches
- **Best practices** - Want to follow established patterns and standards

## Overview

Design comprehensive API documentation and developer portals for exceptional developer experience.

## MANDATORY: Documentation-First Approach

Before designing API portals:

1. **Invoke `docs-management` skill** for API documentation patterns
2. **Verify OpenAPI/AsyncAPI standards** via MCP servers (context7)
3. **Base guidance on industry API documentation best practices**

## Developer Portal Architecture

```text
Developer Portal Components:

┌─────────────────────────────────────────────────────────────────────────────┐
│                           Developer Portal                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │  Getting    │  │    API      │  │   Code      │  │   API       │        │
│  │  Started    │  │  Reference  │  │  Examples   │  │  Console    │        │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘        │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │   SDKs &    │  │  Change     │  │   Status    │  │   Support   │        │
│  │  Libraries  │  │    Log      │  │    Page     │  │   Center    │        │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘        │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                    Authentication & API Keys                         │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘
```

## Portal Content Structure

### Essential Sections

| Section | Purpose | Priority |
|---------|---------|----------|
| **Getting Started** | First-time user guide | P0 |
| **Authentication** | How to authenticate | P0 |
| **API Reference** | Complete endpoint docs | P0 |
| **Code Examples** | Copy-paste samples | P0 |
| **SDKs** | Client libraries | P1 |
| **Changelog** | Version history | P1 |
| **Rate Limits** | Usage constraints | P1 |
| **Errors** | Error handling guide | P1 |
| **Webhooks** | Event notifications | P2 |
| **Best Practices** | Usage recommendations | P2 |

### Getting Started Guide

```markdown
# Getting Started

Get up and running with the [Product] API in 5 minutes.

## Prerequisites

- An account on [Product] ([Sign up free](link))
- An API key ([Get your key](link))
- Basic knowledge of REST APIs

## Quick Start

### 1. Get Your API Key

1. Log in to your [Product] dashboard
2. Navigate to **Settings → API Keys**
3. Click **Create New Key**
4. Copy your key (you won't see it again!)

### 2. Make Your First Request

```bash
curl -X GET "https://api.example.com/v1/users/me" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json
{
  "id": "usr_123abc",
  "email": "[email protected]",
  "name": "Jane Developer",
  "created_at": "2025-01-15T10:30:00Z"
}
```

### 3. Explore the API

- [API Reference](/docs/api-reference) - Complete endpoint documentation
- [Code Examples](/docs/examples) - Ready-to-use samples
- [SDKs](/docs/sdks) - Official client libraries

## Next Steps

| Goal | Resource |
|------|----------|
| Understand authentication | [Authentication Guide](/docs/auth) |
| Browse all endpoints | [API Reference](/docs/api-reference) |
| Handle errors gracefully | [Error Handling](/docs/errors) |
| Go to production | [Production Checklist](/docs/production) |

## Need Help?

- [FAQ](/docs/faq)
- [Community Forum](link)
- [Support](mailto:[email protected])

```text

```

### Authentication Documentation

```markdown
# Authentication

All API requests require authentication using Bearer tokens.

## API Keys

API keys are long-lived credentials for server-to-server communication.

### Creating API Keys

1. Go to **Dashboard → Settings → API Keys**
2. Click **Create New Key**
3. Give it a descriptive name
4. Select the appropriate permissions
5. Copy and securely store the key

### Using API Keys

Include your API key in the `Authorization` header:

```bash
curl -X GET "https://api.example.com/v1/resource" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Key Security Best Practices

| Do | Don't |
|----|-------|
| Store keys in environment variables | Commit keys to source control |
| Use separate keys per environment | Share keys between services |
| Rotate keys regularly | Use keys in client-side code |
| Set minimum required permissions | Use admin keys for all operations |

---

## OAuth 2.0

For user-facing applications, use OAuth 2.0 for secure delegated access.

### Authorization Code Flow

```text
┌──────────┐                               ┌──────────┐
│  Client  │                               │   Auth   │
│   App    │                               │  Server  │
└────┬─────┘                               └────┬─────┘
     │                                          │
     │ 1. Redirect to authorization endpoint    │
     │─────────────────────────────────────────►│
     │                                          │
     │ 2. User authenticates and consents       │
     │                                          │
     │ 3. Redirect back with authorization code │
     │◄─────────────────────────────────────────│
     │                                          │
     │ 4. Exchange code for tokens              │
     │─────────────────────────────────────────►│
     │                                          │
     │ 5. Return access_token and refresh_token │
     │◄─────────────────────────────────────────│
     │                                          │
```

### OAuth Endpoints

| Endpoint | URL |
|----------|-----|
| Authorization | `https://auth.example.com/oauth/authorize` |
| Token | `https://auth.example.com/oauth/token` |
| Revoke | `https://auth.example.com/oauth/revoke` |

### Scopes

| Scope | Description |
|-------|-------------|
| `read:users` | Read user information |
| `write:users` | Create and update users |
| `read:orders` | Read order data |
| `write:orders` | Create and modify orders |

### Token Refresh

```bash
curl -X POST "https://auth.example.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
```

```text

```

## OpenAPI Specification Template

```yaml
openapi: 3.1.0
info:
  title: Product API
  version: 1.0.0
  description: |
    The Product API provides programmatic access to [Product] features.

    ## Authentication

    All endpoints require authentication via Bearer token.
    Get your API key from the [Dashboard](https://dashboard.example.com).

    ## Rate Limiting

    - Standard: 100 requests/minute
    - Premium: 1000 requests/minute

    See [Rate Limits](/docs/rate-limits) for details.

  contact:
    name: API Support
    email: [email protected]
    url: https://example.com/support
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://api-staging.example.com/v1
    description: Staging

security:
  - bearerAuth: []

tags:
  - name: Users
    description: User management operations
  - name: Orders
    description: Order processing operations

paths:
  /users:
    get:
      tags: [Users]
      operationId: listUsers
      summary: List all users
      description: |
        Return