Sankofa/docs/api/README.md

# API Documentation

## GraphQL API

The Sankofa Phoenix API is a GraphQL API built with Apollo Server.

### 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>
```

### Schema

See [schema.graphql](./schema.graphql) for the complete GraphQL schema.

### Queries

#### Get Resources

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

#### Get Sites

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

#### Get Current User

```graphql
query GetMe {
  me {
    id
    email
    name
    role
  }
}
```

### Mutations

#### Login

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

#### Create Resource

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

### Error Handling

The API returns errors in the standard GraphQL error format:

```json
{
  "errors": [
    {
      "message": "Authentication required",
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}
```

### 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

### Examples

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