LogoKagome

API Integration

Connect your Kagome app to any REST API

This guide takes ~20 minutes to complete.

🔧 Setup

API client configured in src/services/client.ts. Update URL:

const API_URL = 'https://your-api-domain.com'

📡 Requests

GET (Queries)

Create hooks for data fetching:

import { useQuery } from '@tanstack/react-query'
import { client } from '@/services/client'

const usePosts = () => {
  return useQuery({
    queryKey: ['posts'],
    queryFn: () => client.get('posts').json(),
  })
}

// Component usage
const PostsList = () => {
  const { data: posts, isLoading } = usePosts()

  if (isLoading) return <Text>Loading...</Text>

  return posts?.map(post => <Text key={post.id}>{post.title}</Text>)
}

POST/PUT/PATCH (Mutations)

Handle data changes:

import { useMutation, useQueryClient } from '@tanstack/react-query'
import { client } from '@/services/client'

const useCreatePost = () => {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: (newPost) => client.post('posts', { json: newPost }).json(),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['posts'] })
    },
  })
}

// Usage
const CreateButton = () => {
  const createPost = useCreatePost()

  return (
    <Button
      onPress={() => createPost.mutate({ title: 'New Post' })}
      disabled={createPost.isPending}
    >
      {createPost.isPending ? 'Creating...' : 'Create Post'}
    </Button>
  )
}

🔐 Authentication

Add bearer tokens:

const client = ky.create({
  headers: {
    Authorization: `Bearer ${getYourAuthToken()}`,
  },
})

📊 Dynamic Queries

Pass parameters:

const usePost = (postId) => {
  return useQuery({
    queryKey: ['post', postId],
    queryFn: () => client.get(`posts/${postId}`).json(),
    enabled: !!postId,
  })
}

📁 File Uploads

Send files:

const useUploadFile = () => {
  return useMutation({
    mutationFn: (formData) =>
      client.post('upload', { body: formData }),
  })
}

⚠️ Error Handling

Basic success/error:

const LoginForm = () => {
  const login = useMutation({
    mutationFn: (credentials) => client.post('auth/login', { json: credentials }).json(),
    onSuccess: (data) => {
      console.log('Logged in:', data.user)
    },
    onError: (error) => {
      console.error('Login failed:', error.message)
    },
  })

  return (
    <Button onPress={() => login.mutate({ email, password })}>
      {login.isPending ? 'Logging in...' : 'Login'}
    </Button>
  )
}

🔄 Caching

  • Queries: Cached for 5 minutes
  • Mutations: Immediate execution
  • Background: Auto refetch on focus

Reference: Check Kagome API for patterns.