# API Services Guide

## Overview

Services are the abstraction layer between frontend components and backend APIs. They encapsulate HTTP requests using the shared `openHands` axios instance and provide typed methods for each endpoint.

Each service is a plain object with async methods.

## Structure

Each service lives in its own directory:

```
src/api/
├── billing-service/
│   ├── billing-service.api.ts    # Service methods
│   └── billing.types.ts          # Types and interfaces
├── organization-service/
│   ├── organization-service.api.ts
│   └── organization.types.ts
└── open-hands-axios.ts           # Shared axios instance
```

## Creating a Service

Use an object literal with named export. Use object destructuring for parameters to make calls self-documenting.

```typescript
// feature-service/feature-service.api.ts
import { openHands } from "../open-hands-axios";
import { Feature, CreateFeatureParams } from "./feature.types";

export const featureService = {
  getFeature: async ({ id }: { id: string }) => {
    const { data } = await openHands.get<Feature>(`/api/features/${id}`);
    return data;
  },

  createFeature: async ({ name, description }: CreateFeatureParams) => {
    const { data } = await openHands.post<Feature>("/api/features", {
      name,
      description,
    });
    return data;
  },
};
```

### Types

Define types in a separate file within the same directory:

```typescript
// feature-service/feature.types.ts
export interface Feature {
  id: string;
  name: string;
  description: string;
}

export interface CreateFeatureParams {
  name: string;
  description: string;
}
```

## Usage

> [!IMPORTANT]
> **Don't call services directly in components.** Wrap them in TanStack Query hooks.
>
> Why? TanStack Query provides:
> - **Caching** - Avoid redundant network requests
> - **Deduplication** - Multiple components requesting the same data share one request
> - **Loading/error states** - Built-in `isLoading`, `isError`, `data` states
> - **Background refetching** - Data stays fresh automatically
>
> Hooks location:
> - `src/hooks/query/` for data fetching (`useQuery`)
> - `src/hooks/mutation/` for writes/updates (`useMutation`)

```typescript
// src/hooks/query/use-feature.ts
import { useQuery } from "@tanstack/react-query";
import { featureService } from "#/api/feature-service/feature-service.api";

export const useFeature = (id: string) => {
  return useQuery({
    queryKey: ["feature", id],
    queryFn: () => featureService.getFeature({ id }),
  });
};
```

## Naming Conventions

| Item | Convention | Example |
|------|------------|---------|
| Directory | `feature-service/` | `billing-service/` |
| Service file | `feature-service.api.ts` | `billing-service.api.ts` |
| Types file | `feature.types.ts` | `billing.types.ts` |
| Export name | `featureService` | `billingService` |