HFID Application Documentation

📋 Application Overview

The HFID (Human Friendly ID) Application is a comprehensive system for managing and tracking stuff in the physical world with automatically generated unique identifiers.

Key Features:

• ✅ Automatic HFID Generation: Unique 6-character identifiers (e.g., A5C-XT9)
• ✅ Organization Management: HFIDs are associated with organizations
• ✅ User Management: Admin and regular user roles with configurable permissions
• ✅ Public/Private HFIDs: Control visibility of HIFD records
• ✅ RESTful API: Full programmatic access with API key authentication

🚀 Getting Started

1. Create an Account

Sign up to create an account.

2. Generate API Key

Visit your profile at Edit Profile to generate your API key for programmatic access.

3. Join an Organization

Contact an administrator to be added to an organization before creating HFIDs.

4. Create Your First HFID

Navigate to Create HFID to create your first hardware record.

HFID Attributes

The following information is tracked with each HFID:

• HFID (unique 6-character ID)
• IPN (Internal Part Number)
• Org (Organization the HFID belongs to)
• Version
• Mfg Date (manufacturing date for device)
• Description
• Public/Private
• Creator
• Created
• Location (text field to store location information)

User Interface

• HFIDs are displayed on the home screen. By default, all HFIDs are displayed, but can be filtered by organization.
• You can also filter by a search term which searches description, IPN, HFID, Organization, Location, or Created By fields.
• The HFID table can be sorted by any column by clicking on the column header.
• Your filter and sort preferences are remembered as you navigate between pages, making it easy to edit HFIDs without losing your place in the filtered list.
• A different random color is chosen for each org button when displaying on the home page.

🔌 API Documentation

Authentication

All API requests require authentication using your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Get your API key from your user profile.

API Endpoints

Method	Endpoint	Description
GET	/api/v1/hfids	List all accessible HFIDs
POST	/api/v1/hfids	Create a new HFID
GET	/api/v1/hfids/:id	Get specific HFID details

🐍 Python API Usage

Installation

Install the required Python library:

pip install requests

Basic Setup

import requests
import json
from datetime import date

class HfidApiClient:
    def __init__(self, base_url, api_key):
        self.base_url = base_url.rstrip('/')
        self.api_key = api_key
        self.headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json',
            'Accept': 'application/json'
        }

# Initialize client
client = HfidApiClient('http://localhost:3000', 'YOUR_API_KEY')

List HFIDs

def list_hfids(self):
    """List all HFIDs accessible to the user"""
    response = requests.get(
        f'{self.base_url}/api/v1/hfids',
        headers=self.headers
    )
    response.raise_for_status()
    return response.json()

# Usage
hfids_response = client.list_hfids()
for hfid in hfids_response['hfids']:
    print(f"HFID: {hfid['hfid']} - {hfid['ipn']}")

Create HFID

def create_hfid(self, ipn, organization_id, version_hw, description,
                 mfg_date=None, public=False):
    """Create a new HFID"""
    if mfg_date is None:
        mfg_date = date.today().isoformat()

    data = {
        'hfid': {
            'ipn': ipn,
            'organization_id': organization_id,
            'version_hw': version_hw,
            'description': description,
            'mfg_date': mfg_date,
            'public': public
        }
    }

    response = requests.post(
        f'{self.base_url}/api/v1/hfids',
        headers=self.headers,
        json=data
    )
    response.raise_for_status()
    return response.json()

# Usage
new_hfid = client.create_hfid(
    ipn="DEMO-001",
    organization_id=1,
    version_hw="v1.0.0",
    description="Demo hardware component",
    public=True
)
print(f"Created HFID: {new_hfid['hfid']['hfid']}")

Get Specific HFID

def get_hfid(self, hfid_id):
    """Get a specific HFID by ID"""
    response = requests.get(
        f'{self.base_url}/api/v1/hfids/{hfid_id}',
        headers=self.headers
    )
    response.raise_for_status()
    return response.json()

# Usage
hfid_details = client.get_hfid(1)
print(f"HFID Details: {hfid_details['hfid']}")

⚠️ Error Handling

Status Code	Error Type	Description
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions for the requested action
404	Not Found	Requested HFID does not exist or is not accessible
422	Validation Error	Request data failed validation (e.g., missing required fields)

⏱️ Rate Limits

Daily Limits: Each user has a configurable daily limit for HFID creation (default: 5 per day).

Rate limits are enforced on HFID creation to prevent abuse. Limits reset daily at midnight and can be configured by administrators for individual users.

Checking Your Limit:

• Current usage is displayed when creating HFIDs via the web interface
• API errors will indicate when you've reached your limit
• Contact an administrator to increase your limit if needed

💻 cURL Examples

List HFIDs

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Accept: application/json" \
     http://localhost:3000/api/v1/hfids

Create HFID

curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "hfid": {
         "ipn": "CURL-001",
         "organization_id": 1,
         "version_hw": "v1.0.0",
         "description": "Created via cURL",
         "mfg_date": "2024-01-20",
         "public": true
       }
     }' \
     http://localhost:3000/api/v1/hfids

Get Specific HFID

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Accept: application/json" \
     http://localhost:3000/api/v1/hfids/1

🆘 Support

Need help with the HFID application?

• Rate Limits: Contact an administrator to increase your daily limit
• Technical Support: Email us at support@hfid.org