api-client-patterns

API Client Patterns

Guidelines for creating and maintaining API clients that communicate with backend services in the T6C project.

Client Organization Principles

One Client Per API Service

• ALWAYS create a dedicated client package for each API service
• Client naming convention: {service-name}-api-client (e.g., blog-api-client, user-api-client)
• Service class naming: {ServiceName}Service (e.g., BlogPostService, UserService)

// ✅ CORRECT - Dedicated client for blog API
export class BlogPostService extends E.Service<BlogPostService>()(
  '@web/BlogPostService',
  {
    dependencies: [FetchHttpClient.layer],
    effect: E.gen(function* () {
      const client = yield* createHttpClient({
        url: envVars.BLOG_SERVICE_URL,
        apiKey: envVars.BLOG_SERVICE_API_KEY,
      })

      return {
        // ... methods
      }
    }),
  },
) {}

Import Patterns

Standard Imports

• Always use relative paths for internal imports
• Import types with type keyword when used only for typing
• Import schemas without type when used for encoding/decoding

// ✅ CORRECT - Import patterns
import {
  FetchHttpClient,
  HttpClientRequest,
  HttpClientResponse,
} from '@effect/platform'
import {
  BlogPost,
  BlogPostCategory,
  type BlogPostPatches,
  CreateBlogPostInput,
  GetBlogPageInput,
} from '@t6c/blog-domain'
import {
  type BlogPostId,
  PaginationSchema,
  type SearchParamsSchema,
  type UserId,
} from '@t6c/domain-common'
import { NotFoundError, createHttpClient } from '@t6c/lib-api'
import { Data, Effect as E, Layer, Schema as S } from 'effect'
import { envVars } from '../config.js'

Method Implementation Patterns

HTTP Method Mapping

• GET requests for data retrieval
• POST requests for resource creation
• PUT requests for resource updates
• DELETE requests for resource deletion

// ✅ CORRECT - HTTP method usage
createDraft: ({ authorId }: { authorId: UserId }) =>
  HttpClientRequest.post('/v1/blog').pipe(
    HttpClientRequest.bodyJson(CreateBlogPostInput.make({ authorId })),
    // ...
  ),

updateAttributes: (blogPostId: string, patches: BlogPostPatches) =>
  HttpClientRequest.put(`/v1/blog/${blogPostId}`).pipe(
    HttpClientRequest.bodyJson(patches),
    // ...
  ),

delete: (id: string) =>
  HttpClientRequest.del(`/v1/blog/${id}`).pipe(
    // ...
  ),