# Web Interface vs REST API

## Overview

Most Forgejo operations are available through the REST API with token authentication. However, some features are only accessible through the web interface and require a browser session (login with cookies).

## Access Comparison

| Feature | REST API | Web Interface | Notes |
|---------|----------|---------------|-------|
| **Repositories** | | | |
| CRUD operations | Yes | Yes | Full API support |
| File read/write | Yes | Yes | API uses base64 encoding |
| Branches | Yes | Yes | Full API support |
| Tags | Yes | Yes | Full API support |
| Commits | Yes | Yes | Full API support |
| **Issues & PRs** | | | |
| CRUD operations | Yes | Yes | Full API support |
| Comments | Yes | Yes | Full API support |
| Labels | Yes | Yes | Full API support |
| Milestones | Yes | Yes | Full API support |
| Reviews | Yes | Yes | Full API support |
| **Organizations** | | | |
| CRUD operations | Yes | Yes | Full API support |
| Teams | Yes | Yes | Full API support |
| Members | Yes | Yes | Full API support |
| **CI/CD (Actions)** | | | |
| Run metadata | Yes | Yes | Status, timing, conclusion |
| Trigger workflow | Yes | Yes | `workflow_dispatch` events |
| **Step-by-step logs** | **No** | **Yes** | See [ci-logs.md](ci-logs.md) |
| Cancel/re-run jobs | Partial | Yes | |
| **User Management** | | | |
| Profile | Yes | Yes | Full API support |
| SSH keys | Yes | Yes | Full API support |
| Tokens | Yes | Yes | Full API support |
| 2FA setup | No | Yes | Web only |
| **Repository Settings** | | | |
| Basic settings | Yes | Yes | Name, description, visibility |
| Branch protection | Yes | Yes | Full API support |
| **Advanced settings** | **Partial** | **Yes** | Some settings web-only |
| Deploy keys | Yes | Yes | Full API support |
| Webhooks | Yes | Yes | Full API support |
| **Admin Panel** | | | |
| User management | Yes | Yes | Full admin API |
| Org management | Yes | Yes | Full admin API |
| **System settings** | **No** | **Yes** | `app.ini` or web panel |
| **Dashboard/monitoring** | **No** | **Yes** | Web panel only |
| **Packages** | | | |
| List/query | Yes | Yes | Full API support |
| Upload | Protocol | Protocol | Native package protocols |
| **Wiki** | | | |
| CRUD operations | Yes | Yes | Full API support |
| **Releases** | | | |
| CRUD operations | Yes | Yes | Full API support |
| Asset upload | Yes | Yes | Multipart via API |
| **Search** | | | |
| Repos/issues/users | Yes | Yes | Full API support |
| **Code search** | **Partial** | **Yes** | Web has better code search |
| **Notifications** | Yes | Yes | Full API support |
| **Diff Viewer** | | | |
| Raw diff | Yes | Yes | API returns plain diff |
| **Syntax-highlighted** | **No** | **Yes** | Web only |
| **File Editor** | | | |
| Edit files | Yes | Yes | API uses base64 |
| **Live preview** | **No** | **Yes** | Web only |

## REST API Accessible (Token Auth)

Everything documented in the other reference files is accessible via the REST API using token authentication:

```bash
curl -H "Authorization: token ${FORGEJO_PAT}" "${FORGEJO_URL}/api/v1/..."
```

This includes:
- Repository CRUD, files, branches, tags, commits
- Issues, pull requests, comments, reviews
- Organizations, teams, members
- Webhooks (repo, org, user, system)
- Releases and assets
- Wiki pages
- Packages (query/delete)
- Notifications
- Search (repos, issues, users, topics, teams)
- Labels, milestones
- Admin operations (users, orgs, cron, emails, quota)
- Settings (API, attachment, repository, UI)
- Git objects (blobs, trees, refs, tags, notes)
- Action run metadata and workflow dispatch

## Web-Only (Requires Login Session)

These features have **no REST API equivalent** and require web session authentication:

### CI/CD Action Logs
Detailed step-by-step logs from workflow runs. See [ci-logs.md](ci-logs.md) for the complete procedure.

### Repository Settings UI
Some advanced repository settings are only configurable through the web interface:
- Archive/unarchive (partially via API)
- Transfer ownership (partially via API)
- Danger zone operations

### System Administration
Instance-level settings that require the admin web panel:
- `app.ini` configuration
- Server monitoring dashboard
- Maintenance mode

### File Editor with Preview
The web editor provides live Markdown preview and syntax highlighting during editing. The API only supports raw content operations.

### Diff Viewer with Syntax Highlighting
The web interface renders diffs with full syntax highlighting. The API returns raw unified diff format.

## Hybrid (Partial REST, Full Web)

### Action Runs
- **REST**: Run metadata (status, conclusion, timing, SHA, event type), trigger `workflow_dispatch`
- **Web**: Detailed step logs, log streaming, re-run/cancel buttons

### Repository Settings
- **REST**: `PATCH /api/v1/repos/{owner}/{repo}` for basic settings (name, description, visibility, default branch, etc.)
- **Web**: Full settings panel including advanced options, danger zone, and visual configuration

### Code Search
- **REST**: `GET /api/v1/repos/search` searches repo names/descriptions/topics
- **Web**: Full-text code search across file contents with syntax-highlighted results

## When to Use Web Authentication

Use web session authentication when you need to:

1. **Read CI/CD logs** - No API endpoint exists for step logs
2. **Access advanced settings** - Some repo/instance settings lack API endpoints
3. **Get rendered views** - Syntax-highlighted diffs, previews

For web authentication details, see [ci-logs.md](ci-logs.md) which covers the login flow with CSRF tokens and cookie management.

For everything else, prefer the REST API with token authentication - it is simpler, more reliable, and designed for programmatic access.
