API Documentation

Backend API Endpoints

The application communicates with a backend API for user management, organizations, and billing:

Authentication

• POST /authentication/password-login - User login
• POST /authentication/verify-user - Verify user email
• PATCH /authentication/recovery-password - Recover user password
• PATCH /user/update/{userId} - Update user profile

Organizations

• GET /organization/user - Get user organizations
• POST /organization - Create organization
• PATCH /organization/member/{org_id} - Add member
• PATCH /organization/update-role/{org_id} - Update member role

Projects

• GET /project/orgs/{orgId} - Get organization projects
• POST /project/create - Create project
• GET /project/{projectId} - Get project details
• PATCH /project/{projectId} - Update project
• DELETE /project/{projectId} - Delete project

Note: /src/redux/features/project/project-api.ts is responsible for handling project-related API calls.

Subscriptions

• GET /package - Get available packages
• POST /subscription - Create subscription
• GET /subscription/user/{userId} - Get user subscription

Note: /src/redux/features/project/package-api-slice.ts is responsible for handling project-related API calls.

GitHub API Integration

Direct GitHub API integration through Octokit:

Content API and Commit API

The application uses two main API slices for GitHub operations:

Content API - Repository data retrieval and management:

• GET /user/installations - Get GitHub App installations with token authentication
• GET /app/installations/{installation_id} - Get specific installation details
• GET /user/installations/{installation_id}/repositories - Get accessible repositories for installation
• GET /repos/{owner}/{repo}/git/trees/{tree_sha} - Get repository file tree (recursive support)
• GET /repos/{owner}/{repo}/contents/{path} - Get file content with frontmatter parsing
• GET /repos/{owner}/{repo}/branches - Get repository branches (up to 100 per page)
• GET /repos/{owner}/{repo} - Get single repository details
• GET /users/{username}/repos - Get user repositories
• GET /repos/{owner}/{repo}/deployments - Get deployment information
• GET /repos/{owner}/{repo}/deployments/{deployment_id}/statuses - Get deployment status

Commit API - Git operations and file modifications:

• GET /repos/{owner}/{repo}/commits - Get commit history with path filtering
• GET /repos/{owner}/{repo}/git/ref/{ref} - Get branch reference details
• GET /repos/{owner}/{repo}/branches/{branch} - Get specific branch information
• GET /user - Get authenticated user details for commit attribution
• POST /repos/{owner}/{repo}/git/blobs - Create file blob with base64 encoding support
• POST /repos/{owner}/{repo}/git/trees - Create tree object with base tree support
• POST /repos/{owner}/{repo}/git/commits - Create commit with author/committer details
• PATCH /repos/{owner}/{repo}/git/refs/{ref} - Update branch reference (force push support)

Special Operations & Advanced Features:

Complex Mutations:

• updateFiles mutation - Complete Git workflow (blob creation → tree construction → commit → branch update)
  • Supports multiple file operations in a single commit
  • Automatic base64 encoding for media files
  • Co-author attribution with Co-authored-by trailer
  • Optimistic UI updates with cache invalidation
• renameFolder mutation - Atomic folder renaming operations
  • Creates new tree structure with renamed paths
  • Preserves file history and maintains Git integrity
  • Automatic cache updates for affected file trees

Content Processing:

• Frontmatter Detection: Automatic detection of YAML (---), TOML (+++, ---toml) formats
• Content Parsing: Intelligent parsing with fmDetector and parseContentJson utilities
• Media Handling: Base64 encoding detection via checkMedia function
• Tree Transformation: Directory structure optimization with pathToDir utility

Cache Management:

• RTK Query Integration: Automatic cache invalidation and updates
• Optimistic Updates: Immediate UI feedback before server confirmation
• Selective Updates: Targeted cache updates based on file path patterns

Legacy Support & Migration:

• Automatic Migration: .zeonCms → .sitepins folder conversion
• Configuration Detection: Automatic site config loading and parsing
• Backward Compatibility: Support for legacy folder structures

Note: Ensure that the GitHub App has the necessary permissions to access the repository.
See the GitHub REST API documentation  for more details.

React Hooks & API Usage

Content API Hooks:

// Repository and installation management
const { data: installations } = useGetInstallationsQuery();
const { data: installation } = useGetInstallationQuery({ installation_id });
const { data: repos } = useGetReposByInstallationIdQuery({ installation_id });
 
// Repository content operations
const { data: branches } = useGetBranchesQuery({ owner, repo });
const { data: repository } = useGetSingleRepoQuery({ owner, repo });
const { data: userRepos } = useGetUserReposQuery({ username });
const { data: trees } = useGetTreesQuery({
  owner,
  repo,
  tree_sha,
  recursive: "1",
});
 
// File content and configuration
const { data: content } = useGetContentQuery({
  owner,
  repo,
  path,
  ref,
  parser: true,
});
const { data: config } = useGetSiteConfigQuery({ owner, repo, path, ref });
const { data: image } = useGetImageQuery({ owner, repo, path, ref });
 
// Deployment monitoring
const { data: deployStatus } = useGetDeployStatusQuery({ owner, repo });

Commit API Hooks:

// Git operations
const { data: commits } = useGetCommitQuery({ owner, repo, sha, path });
const [updateFiles, { isLoading, error }] = useUpdateFilesMutation();
 
// Example usage
await updateFiles({
  owner: "username",
  repo: "repository",
  tree: "main",
  files: [{ path: "content/post.md", content: "# Hello World" }],
  message: "Add new post",
  description: "Created via Sitepins CMS",
});