Frontend Integration

APSO backends provide standard REST APIs that work with any frontend framework. The TypeScript SDK offers type-safe integration for JavaScript-based frontends.

Supported Frameworks

Hooks and patterns for React apps

React

Server components and API routes

Next.js

Mobile app integration

React Native

Cross-platform mobile development

Flutter

Quick Start

Install the SDK


npm install @apso/sdk

Configure the Client


// lib/apso.ts
import { createClient } from '@apso/sdk';
 
export const apso = createClient({
  baseUrl: process.env.NEXT_PUBLIC_API_URL!,
  // Token will be set after authentication
});
 
// Set token after login
export const setAuthToken = (token: string) => {
  apso.setToken(token);
};

Use in Components


// components/ProjectList.tsx
import { useEffect, useState } from 'react';
import { apso } from '../lib/apso';
import type { Project } from '@apso/sdk';
 
export function ProjectList() {
  const [projects, setProjects] = useState<Project[]>([]);
  const [loading, setLoading] = useState(true);
 
  useEffect(() => {
    apso.projects.findMany()
      .then(setProjects)
      .finally(() => setLoading(false));
  }, []);
 
  if (loading) return <div>Loading...</div>;
 
  return (
    <ul>
      {projects.map(project => (
        <li key={project.id}>{project.name}</li>
      ))}
    </ul>
  );
}

Authentication Flow

Most frontends follow this pattern:


// 1. User logs in
const { token, user } = await apso.auth.login({
  email: 'user@example.com',
  password: 'password'
});
 
// 2. Store token (localStorage, cookies, etc.)
localStorage.setItem('token', token);
 
// 3. Set token on SDK client
apso.setToken(token);
 
// 4. Make authenticated requests
const projects = await apso.projects.findMany();

API Patterns

REST Endpoints

All APSO backends expose consistent REST endpoints:

Method	Endpoint	Description
GET	`/api/v1/{entity}`	List all
GET	`/api/v1/{entity}/:id`	Get one
POST	`/api/v1/{entity}`	Create
PATCH	`/api/v1/{entity}/:id`	Update
DELETE	`/api/v1/{entity}/:id`	Delete

Query Parameters


GET /api/v1/projects?limit=20&offset=0&sort=createdAt:desc
GET /api/v1/projects?filter[status]=active
GET /api/v1/projects?include=tasks

Error Handling


try {
  const project = await apso.projects.create({
    name: 'New Project'
  });
} catch (error) {
  if (error.status === 400) {
    // Validation error
    console.log(error.errors);
  } else if (error.status === 401) {
    // Unauthorized - redirect to login
    router.push('/login');
  } else if (error.status === 403) {
    // Forbidden - no access
    showError('You do not have permission');
  }
}

Environment Variables


# .env.local (Next.js)
NEXT_PUBLIC_API_URL=http://localhost:3001
 
# .env (Vite/React)
VITE_API_URL=http://localhost:3001