Developer Documentation/SDK Reference/Web API

Web API

Make HTTP requests to external APIs.

Overview

The Web API allows your extension to make HTTP requests to external APIs and open URLs in the user's browser.

import { useHaexClient } from '@haex-space/vault-sdk/vue'

const client = useHaexClient()

// Fetch data from an API
const response = await client.web.fetchAsync('https://api.example.com/data')

// Convenience methods for common formats
const json = await client.web.fetchJsonAsync('https://api.example.com/users')
const text = await client.web.fetchTextAsync('https://example.com/readme.txt')
const blob = await client.web.fetchBlobAsync('https://example.com/image.png')

// Open URL in default browser
await client.web.openAsync('https://example.com')

All URLs must be declared in your manifest permissions. Requests to undeclared URLs will fail.

Making Requests

The fetchAsync method provides full control over HTTP requests:

Basic Request

// fetchAsync(url: string, options?: WebRequestOptions): Promise<WebResponse>

// Simple GET request
const response = await client.web.fetchAsync('https://api.example.com/users')
console.log('Status:', response.status)
console.log('Data:', response.data)

// POST request with JSON body
const createResponse = await client.web.fetchAsync('https://api.example.com/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer token123'
  },
  body: JSON.stringify({ name: 'John', email: 'john@example.com' })
})

// Handle response
if (createResponse.status === 201) {
  const user = JSON.parse(createResponse.data)
  console.log('Created user:', user)
}

Request with Headers

// Request with custom headers
const response = await client.web.fetchAsync('https://api.github.com/user', {
  method: 'GET',
  headers: {
    'Accept': 'application/vnd.github.v3+json',
    'Authorization': 'token ghp_xxxx'
  }
})

// Access response headers
console.log('Rate limit:', response.headers['x-ratelimit-remaining'])

Convenience Methods

These methods simplify common fetch patterns:

fetchJsonAsync()

// fetchJsonAsync<T>(url: string, options?: WebRequestOptions): Promise<T>
// Fetches and parses JSON automatically

interface User {
  id: number
  name: string
  email: string
}

// Type-safe JSON fetching
const users = await client.web.fetchJsonAsync<User[]>('https://api.example.com/users')

for (const user of users) {
  console.log(user.name, user.email)
}

// With POST
const newUser = await client.web.fetchJsonAsync<User>('https://api.example.com/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Jane', email: 'jane@example.com' })
})

fetchTextAsync()

// fetchTextAsync(url: string, options?: WebRequestOptions): Promise<string>
// Fetches and returns text content

const readme = await client.web.fetchTextAsync('https://raw.githubusercontent.com/user/repo/main/README.md')
console.log(readme)

// Fetch and process CSV
const csv = await client.web.fetchTextAsync('https://example.com/data.csv')
const rows = csv.split('\n').map(row => row.split(','))

fetchBlobAsync()

// fetchBlobAsync(url: string, options?: WebRequestOptions): Promise<Blob>
// Fetches binary data as Blob

const imageBlob = await client.web.fetchBlobAsync('https://example.com/avatar.png')

// Create object URL for display
const imageUrl = URL.createObjectURL(imageBlob)
imageElement.src = imageUrl

// Convert to Uint8Array if needed
const arrayBuffer = await imageBlob.arrayBuffer()
const bytes = new Uint8Array(arrayBuffer)

Open URL in Browser

Open a URL in the user's default browser:

// openAsync(url: string): Promise<void>
// Opens URL in the user's default browser

// Open a webpage
await client.web.openAsync('https://example.com')

// Open documentation
await client.web.openAsync('https://docs.example.com/getting-started')

// Open with parameters
const searchQuery = encodeURIComponent('haex vault')
await client.web.openAsync(`https://google.com/search?q=${searchQuery}`)

HTTP Permissions

All URLs must be declared in your manifest. Check permissions before making requests:

// HTTP permissions must be declared in manifest.json

// manifest.json
{
  "permissions": {
    "http": [
      { "target": "https://api.example.com/**" },
      { "target": "https://*.github.com/*" }
    ]
  }
}

// Check permission before fetching
const canFetch = await client.checkWebAsync('https://api.example.com/users')

if (canFetch) {
  const data = await client.web.fetchJsonAsync('https://api.example.com/users')
} else {
  console.log('No permission to fetch from this URL')
}

For detailed permission information, see the Permissions Guide

Type Definitions

TypeScript interfaces for web requests:

interface WebRequestOptions {
  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
  headers?: Record<string, string>
  body?: string
  timeout?: number  // milliseconds
}

interface WebResponse {
  status: number
  statusText: string
  headers: Record<string, string>
  data: string
}

// Example response
{
  status: 200,
  statusText: 'OK',
  headers: {
    'content-type': 'application/json',
    'x-request-id': 'abc123'
  },
  data: '{"users": [...]}'
}

←Filesystem API Introduction→