Custom Browser API

Overview

The FPS platform provides a global browser API for custom HTML components. This API handles authentication automatically using secure HTTP-only cookies, eliminating the need to manage session tokens in your code.

Available APIs

window.callEndpoint()

Makes authenticated API requests to your backend endpoints.

Signature:

window.callEndpoint(endpoint, method, body, params, callback, options)

Parameters:

• endpoint (string) - The API endpoint name (e.g., 'getFeatures', 'updateUser')

• method (string) - HTTP method: 'GET', 'POST', 'PUT', 'DELETE'

• body (object) - Request body for POST/PUT/DELETE requests (ignored for GET)

• params (object) - Query parameters (e.g., { page: 1, limit: 10 })

• callback (function) - Callback function: (status, data, settings, fullResponse) => {}

  • status (string) - 'ok' or 'error'

  • data (array|object) - Response data

  • settings (object) - View settings (optional)

  • fullResponse (object) - Full API response

• options (object) - Optional settings (e.g., { signal: abortController.signal })

Returns: Nothing (results passed to callback)

Examples

Basic GET Request

// Fetch user list
window.callEndpoint(
  'getUsers',           // endpoint
  'GET',                // method
  undefined,            // body (not used for GET)
  { limit: 10 },        // params
  (status, data) => {   // callback
    if (status === 'ok') {
      console.log('Users:', data);
      // Render your data here
    } else {
      console.error('Error:', data);
    }
  }
);

POST Request with Body

// Create new item
window.callEndpoint(
  'createItem',
  'POST',
  { 
    title: 'New Item',
    description: 'Item description',
    price: 99.99
  },
  {},
  (status, data) => {
    if (status === 'ok') {
      console.log('Created:', data);
    }
  }
);

Update Request

// Update existing record
window.callEndpoint(
  'updateItem',
  'POST',
  { 
    id: '123',
    title: 'Updated Title'
  },
  {},
  (status, data, settings, fullResponse) => {
    if (status === 'ok') {
      console.log('Updated successfully');
      console.log('Full response:', fullResponse);
    }
  }
);

Search with Filters

// Search with query parameters
window.callEndpoint(
  'searchItems',
  'GET',
  undefined,
  {
    _value: 'search term',
    category: 'electronics',
    minPrice: 50
  },
  (status, data) => {
    if (status === 'ok') {
      document.getElementById('results').innerHTML = 
        data.map(item => `<div>${item.title}</div>`).join('');
    }
  }
);

With Abort Controller

const abortController = new AbortController();

window.callEndpoint(
  'getLargeData',
  'GET',
  undefined,
  {},
  (status, data) => {
    console.log('Data received:', data);
  },
  { signal: abortController.signal }
);

// Cancel request after 5 seconds
setTimeout(() => abortController.abort(), 5000);

Authentication

All requests are automatically authenticated. The session token is stored in a secure HTTP-only cookie and is automatically included with every request. You don't need to:

• Store tokens in localStorage/sessionStorage

• Manually add authorization headers

• Handle token refresh

The platform manages authentication for you.

Error Handling

window.callEndpoint(
  'riskyOperation',
  'POST',
  { data: 'value' },
  {},
  (status, data) => {
    if (status === 'error') {
      // API returned an error
      console.error('API Error:', data.msg || data);
      // Show error to user
      alert('Operation failed: ' + (data.msg || 'Unknown error'));
    } else {
      // Success
      console.log('Success:', data);
    }
  }
);

Migration Guide

If you have existing code using fetch() directly, you need to migrate to window.callEndpoint() for authentication to work properly.

Before (Old Code - Will Not Work)

// ❌ This will NOT work - no access to session token
fetch('https://api.example.com/endpoint?sessionID=TOKEN', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ key: 'value' })
})
.then(res => res.json())
.then(data => console.log(data));

After (New Code - Works)

// ✅ This works - automatic authentication
window.callEndpoint(
  'endpoint',
  'POST',
  { key: 'value' },
  {},
  (status, data) => {
    if (status === 'ok') {
      console.log(data);
    }
  }
);

File Upload with FormData

// Upload file to backend
const fileInput = document.getElementById('fileInput');

fileInput.addEventListener('change', (e) => {
  const file = e.target.files[0];
  
  if (!file) return;
  
  // Create FormData and append file
  const formData = new FormData();
  formData.append('file', file);
  
  // You can add additional fields
  formData.append('description', 'My uploaded file');
  formData.append('category', 'documents');
  
  window.callEndpoint(
    'uploadFile',         // endpoint name
    'POST',               // method
    formData,             // FormData body (not JSON!)
    { 
      fileStorage: 'my-storage',
      maxSize: 10485760  // optional params
    },
    (status, data) => {
      if (status === 'ok') {
        console.log('File uploaded:', data);
        // data might contain file URL, ID, etc.
        alert('File uploaded successfully!');
      } else {
        console.error('Upload failed:', data);
        alert('Upload error: ' + (data.msg || 'Unknown error'));
      }
    }
  );
});

Important for file uploads:

• Use FormData instead of plain object for body parameter

• The browser automatically sets correct Content-Type with boundary for multipart/form-data

• Field name 'file' must match your backend FileUpload data structure field

• You can append multiple files or additional text fields to FormData

AI Migration Prompt

Use this prompt with an AI assistant to automatically convert your old code:

---

PROMPT:

I need to migrate my fetch() API calls to use window.callEndpoint() for the FPS platform.

OLD PATTERN (fetch):
- Direct fetch() calls to API endpoints
- Manual sessionID/token in URL or headers
- Promise-based (.then/.catch)

NEW PATTERN (window.callEndpoint):
- window.callEndpoint(endpoint, method, body, params, callback)
- Automatic authentication (no token needed)
- Callback-based

CONVERSION RULES:
1. Extract endpoint name from URL (last segment)
2. Convert HTTP method (GET/POST/PUT/DELETE)
3. Move body from fetch options to 3rd parameter
4. Move URL query params to 4th parameter (as object)
5. Convert .then(res => res.json()).then(data => ...) to callback: (status, data) => { if (status === 'ok') { ... } }
6. Remove all sessionID, token, Authorization headers
7. Keep only 'signal' in options if using AbortController

Please convert this code:

[PASTE YOUR CODE HERE]

---

Example Conversion:

Input:

fetch('/api/sl?sl=getFeatures&limit=10', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ category: 'electronics' })
})
.then(res => res.json())
.then(data => {
  console.log(data);
  renderItems(data);
})
.catch(err => console.error(err));

AI Output:

window.callEndpoint(
  'getFeatures',
  'POST',
  { category: 'electronics' },
  { limit: 10 },
  (status, data) => {
    if (status === 'ok') {
      console.log(data);
      renderItems(data);
    } else {
      console.error(data);
    }
  }
);

Best Practices

1. Always check status in the callback before using data

2. Don't store tokens - authentication is handled automatically

3. Use meaningful endpoint names that match your backend structure

4. Handle errors gracefully with user-friendly messages

5. Use AbortController for long-running requests that can be cancelled

6. Test in browser console before integrating into your component

Troubleshooting

Request not authenticated

• Make sure you're logged in to the platform

• Check that the user has valid session (check browser cookies for token_new_*)

Endpoint not found

• Verify the endpoint name matches your backend configuration

• Check for typos in the endpoint string

Data not received

• Verify the callback function is being called

• Check browser console for errors

• Inspect network tab in DevTools to see the actual request/response

Additional Resources

• See SESSION_AUTH.md for details on session management

• Check your backend API documentation for available endpoints

• Use browser DevTools Network tab to debug requests