Sankofa/docs/api/API_CONTRACTS.md

# Sankofa Phoenix API Contracts

This document defines the GraphQL API contracts for the Sankofa Phoenix platform. This serves as the contract between frontend and backend teams during parallel development.

**Last Updated**: 2024  
**Version**: 1.0.0

## GraphQL Endpoint

- **Development**: `http://localhost:4000/graphql`
- **Production**: `https://api.sankofa.nexus/graphql`

## Authentication

All queries and mutations (except `login`) require authentication via JWT token:

```http
Authorization: Bearer <token>
```

## Core Types

### Resource

```graphql
type Resource {
  id: ID!
  name: String!
  type: ResourceType!
  status: ResourceStatus!
  site: Site!
  metadata: JSON
  createdAt: DateTime!
  updatedAt: DateTime!
}
```

### Site

```graphql
type Site {
  id: ID!
  name: String!
  region: String!
  status: SiteStatus!
  resources: [Resource!]!
  createdAt: DateTime!
  updatedAt: DateTime!
}
```

### ResourceInventoryItem

```graphql
type ResourceInventoryItem {
  id: ID!
  resourceType: String!
  provider: ResourceProvider!
  providerId: String!
  providerResourceId: String
  name: String!
  region: String
  site: Site
  metadata: JSON
  tags: [String!]!
  discoveredAt: DateTime!
  lastSyncedAt: DateTime!
  createdAt: DateTime!
  updatedAt: DateTime!
}
```

## Queries

### Get Resources

```graphql
query GetResources($filter: ResourceFilter) {
  resources(filter: $filter) {
    id
    name
    type
    status
    site {
      id
      name
      region
    }
    createdAt
    updatedAt
  }
}
```

### Get Resource Inventory

```graphql
query GetResourceInventory($filter: ResourceInventoryFilter) {
  resourceInventory(filter: $filter) {
    id
    name
    resourceType
    provider
    region
    tags
    metadata
    lastSyncedAt
  }
}
```

### Get Sites

```graphql
query GetSites {
  sites {
    id
    name
    region
    status
    resources {
      id
      name
      type
    }
  }
}
```

## Mutations

### Login

```graphql
mutation Login($email: String!, $password: String!) {
  login(email: $email, password: $password) {
    token
    user {
      id
      email
      name
      role
    }
  }
}
```

### Create Resource

```graphql
mutation CreateResource($input: CreateResourceInput!) {
  createResource(input: $input) {
    id
    name
    type
    status
    site {
      id
      name
    }
  }
}
```

## Subscriptions

### Resource Updates

```graphql
subscription ResourceUpdated($id: ID!) {
  resourceUpdated(id: $id) {
    id
    name
    status
    updatedAt
  }
}
```

## Error Codes

- `UNAUTHENTICATED`: Authentication required
- `FORBIDDEN`: Insufficient permissions
- `NOT_FOUND`: Resource not found
- `VALIDATION_ERROR`: Input validation failed
- `SERVER_ERROR`: Internal server error

## Rate Limiting

- 100 requests per minute per IP
- 1000 requests per hour per authenticated user

## Mock Data

For frontend development, use the following mock responses structure:

```typescript
// Mock Resource
{
  id: "uuid",
  name: "example-resource",
  type: "VM",
  status: "RUNNING",
  site: {
    id: "uuid",
    name: "US East Primary",
    region: "us-east-1"
  },
  createdAt: "2024-01-01T00:00:00Z",
  updatedAt: "2024-01-01T00:00:00Z"
}
```

See [examples.md](./examples.md) for more detailed examples.