Skip to main content

HTTP API Repo

The HTTP API repo allows you to sync bookmarks from any HTTP endpoint that returns bookmark data in JSON or YAML format.

HTTP API repos fetch bookmarks by making HTTP requests to a specified URL. The extension supports both JSON and YAML response formats.

Properties​

  • All Common Properties
  • URL - The full URL of the API endpoint
    • Must be a valid HTTP or HTTPS URL
    • Must be accessible from your browser (CORS may be required)
    • Should return bookmark data in the expected format
  • Format - The response format (JSON or YAML)

Bookmark Data Format​

The API endpoint should return bookmark data in one of these formats:

JSON Format​

{
  "items": [
    {
      "title": "Example Bookmark",
      "url": "https://example.com",
      "children": [
        {
          "title": "Nested Bookmark",
          "url": "https://example.com/nested"
        }
      ]
    }
  ]
}

YAML Format​

items:
  - title: Example Bookmark
    url: https://example.com
    children:
      - title: Nested Bookmark
        url: https://example.com/nested

Bookmark Object Structure​

Each bookmark item can have:

  • title (required) - The bookmark title
  • url (required) - The bookmark URL
  • children (optional) - Array of nested bookmarks (for folders)

Example Use Cases​

  • Public API: https://api.example.com/bookmarks (JSON)
  • Self-Hosted Service: http://localhost:3000/api/bookmarks (JSON)
  • GitHub Gist: https://gist.githubusercontent.com/username/gist-id/raw/bookmarks.json (JSON)

Authentication​

Currently, the extension supports public APIs only. For authenticated APIs, consider using a public proxy that adds authentication headers or a service that generates public URLs with embedded tokens.

Error Handling​

If a sync fails, the extension records the error in fetch history and provides advice based on the error type:

  • 404 - URL not found
  • 403 - Access forbidden
  • 401 - Authentication required
  • 500 - Server error
  • Network errors - Connection issues

Check the fetch history in the extension options page for detailed error information.

Best Practices​

  1. Use HTTPS - Always use HTTPS URLs when possible for security
  2. Validate your data - Ensure your API returns data in the correct format
  3. Handle errors gracefully - Your API should return appropriate HTTP status codes
  4. Consider rate limiting - Don't set sync frequency too high if your API has rate limits
  5. Test first - Use "Fetch now" to test your repo before relying on automatic sync

Troubleshooting​

"URL is not accessible" Error​

  • Check that the URL is correct and accessible
  • Verify CORS headers if accessing from a different domain
  • Test the URL directly in your browser

"Data format is invalid" Error​

  • Verify your API returns data in the expected format
  • Check that the items array exists at the root level
  • Ensure each bookmark has both title and url fields

Bookmarks Not Syncing​

  • Check the sync frequency setting
  • Verify the last sync time in the repo list
  • Check the fetch history for error details
  • Try a manual "Fetch now" to test