RIF API Documentation

Overview

The RifGenerationJobView is a REST API endpoint class that provides asynchronous job-based operations for generating, retrieving, updating, and deleting Rack Inventory Files (RIF).

Architecture

graph TD
    A[Client Request] --> B[RifGenerationJobView]
    B --> C[handle_rif_generation]
    C --> D[Job.enqueue]
    D --> E[rif_services task]
    E --> F[RifApi]
    F --> G{HTTP Method}
    G -->|GET| H[RifApi.get]
    G -->|POST| I[RifApi.post]
    G -->|PATCH| J[RifApi.patch]
    G -->|DELETE| K[RifApi.delete]
    H --> L[RifGeneratorService]
    L --> M[Generate RIF Data]
    I --> N[Create RIF in GitHub]
    J --> O[Update RIF in GitHub]
    K --> P[Delete RIF from GitHub]

Supported HTTP Methods

The RifGenerationJobView supports all four primary HTTP methods:

Method	Purpose	Handler Method
GET	Retrieve RIF data for a rack	`get()`
POST	Create a new RIF file in GitHub	`post()`
PATCH	Update an existing RIF file in GitHub	`patch()`
DELETE	Delete an existing RIF file from GitHub	`delete()`

Request Parameters

Query Parameters

The API accepts two different parameter sets to identify a rack:

Option 1: Individual Components (All Required Together)

Parameter	Type	Required	Description	Example
`site`	string	Yes*	Data center site name	`dal09`
`zone`	string	Yes*	Zone identifier	`qz2`
`room`	string	Yes*	Server room name or identifier	`sr09`
`rack`	string	Yes*	Rack identifier	`rk123`
`gen2`	boolean	No	Indicates if rack architecture is Gen2	`true` or `false`

*Required when rackname is not provided

Option 2: Composite Identifier

Parameter	Type	Required	Description	Example
`rackname`	string	Yes*	Full rack name in format: site-zone-room-rack	`che1-qz1-sr1-rk002`
`gen2`	boolean	No	Indicates if rack architecture is Gen2	`true` or `false`

*Required when individual components are not provided

Request Rules

You must provide EITHER: - rackname alone

OR - All four parameters: site, zone, room, and rack together

If both are provided, rackname takes priority.

Request Body (POST/PATCH/DELETE)

For POST, PATCH, and DELETE operations, the request body should contain the RIF data in JSON format following the platform inventory schema.

Example POST Body:

{
  "global": {
    "fzone": "dal09",
    "qzone": "qz2",
    "room": "sr09",
    "rackid": "rk123"
  },
  "servers": [
    {
      "hostname": "server01",
      "position": "U01",
      "model": "Dell R640"
    }
  ]
}

Response Format

Immediate Response (Job Creation)

All requests return an immediate response with job tracking information:

{
  "status": "pending",
  "job_pk": 12345,
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response Fields: - status: Current job status (typically "pending" initially) - job_pk: Primary key of the job in the database - job_id: UUID for tracking the job

HTTP Status Code: 202 Accepted

Job Result (Asynchronous)

Once the background job completes, the result contains:

{
  "success": true,
  "stdout": "<RIF data or operation result>",
  "stderr": "",
  "exit_code": 0
}

Result Fields: - success: Boolean indicating operation success - stdout: Output data (RIF content for GET, confirmation for POST/PATCH/DELETE) - stderr: Error messages if any - exit_code: Exit code (0 for success, -1 for failure)

API Endpoints

GET - Retrieve RIF Data

Retrieves the generated RIF data for a specified rack without creating a file in GitHub.

Endpoint: /api/asset-index/rif-generation/

Method: GET

Example Request:

curl -X GET "https://api.example.com/api/asset-index/rif-generation/?site=dal09&zone=qz2&room=sr09&rack=rk123" \
  -H "Authorization: Bearer <token>"

Example Request (with rackname):

curl -X GET "https://api.example.com/api/asset-index/rif-generation/?rackname=che1-qz1-sr1-rk002" \
  -H "Authorization: Bearer <token>"

Processing Flow: 1. Job is enqueued via Job.enqueue() 2. Background task rif_services() is executed 3. RifApi.get() generates RIF data 4. RifGeneratorService creates the RIF content 5. Result is stored in job output

POST - Create New RIF File

Creates a new RIF file in the GitHub repository under region/rif/ directory.

Endpoint: /api/asset-index/rif-generation/

Method: POST

Example Request:

curl -X POST "https://api.example.com/api/asset-index/rif-generation/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "global": {
      "fzone": "dal09",
      "qzone": "qz2",
      "room": "sr09",
      "rackid": "rk123"
    },
    "servers": [...]
  }'

Processing Flow: 1. Validates JSON structure contains required global fields: fzone, qzone, room, rackid 2. Generates filename: <fzone>.<qzone>.<room>.<rackid>.yaml 3. Checks if file already exists in GitHub 4. If file exists, returns error (use PATCH to update) 5. Creates new branch in GitHub repository 6. Commits new YAML file to branch 7. Creates pull request for review

Error Conditions: - Missing required global fields → exit_code: -1 - File already exists → exit_code: -1 (suggests using PATCH)

PATCH - Update Existing RIF File

Updates an existing RIF file in the GitHub repository.

Endpoint: /api/asset-index/rif-generation/

Method: PATCH

Example Request:

curl -X PATCH "https://api.example.com/api/asset-index/rif-generation/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "global": {
      "fzone": "dal09",
      "qzone": "qz2", 
      "room": "sr09",
      "rackid": "rk123"
    },
    "servers": [...]
  }'

Processing Flow: 1. Validates JSON structure 2. Generates filename from global fields 3. Retrieves existing file SHA from GitHub 4. Updates file content in new branch 5. Creates pull request with changes

DELETE - Remove RIF File

Deletes an existing RIF file from the GitHub repository.

Endpoint: /api/asset-index/rif-generation/

Method: DELETE

Example Request:

curl -X DELETE "https://api.example.com/api/asset-index/rif-generation/?rackname=che1-qz1-sr1-rk002" \
  -H "Authorization: Bearer <token>"

Processing Flow: 1. Identifies file based on query parameters 2. Locates file in GitHub repository 3. Creates branch for deletion 4. Removes file from branch 5. Creates pull request for deletion

Error Handling

Common Error Scenarios

Error	HTTP Status	Description	Resolution
Invalid Parameters	400	Missing required rack identification parameters	Provide either `rackname` or all four components
File Already Exists	400	Attempting to POST when file exists	Use PATCH method instead
File Not Found	404	Attempting to PATCH/DELETE non-existent file	Verify file exists or use POST
Authentication Failed	401	Missing or invalid authentication	Provide valid Bearer token
GitHub API Error	500	GitHub repository access issues	Check GitHub token and repository permissions

Error Response Format

{
  "success": false,
  "stdout": "",
  "stderr": "Error message describing the issue",
  "exit_code": -1
}

Authentication & Authorization

Authentication: Required via IsAuthenticated permission class
Authorization: Bearer token authentication
User Context: Requests are executed in the context of the authenticated user
GitHub Access: Requires valid GitHub token for repository operations

Configuration

Environment Variables

GIT_TOKEN: GitHub personal access token
GIT_REPO_OWNER: GitHub repository owner
GIT_REPO_REMOTE: GitHub repository name
GIT_USER: Git user for commits
GIT_EMAIL: Git email for commits
LOCAL_PI_PATH: Local platform inventory path

Usage Examples

Complete Workflow Example

Create RIF Job:

curl -X POST "https://api.example.com/api/asset-index/rif-generation/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "global": {
      "fzone": "dal09",
      "qzone": "qz2",
      "room": "sr09", 
      "rackid": "rk123"
    }
  }'

Response:

{
  "status": "pending",
  "job_pk": 12345,
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}

Check Job Status (using separate job status API):

curl -X GET "https://api.example.com/api/jobs/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Bearer <token>"

Job Completion Result:

{
  "success": true,
  "stdout": "RIF file dal09.qz2.sr09.rk123.yaml created successfully",
  "stderr": "",
  "exit_code": 0
}

Best Practices

Parameter Validation

Always provide either rackname OR all four components (site, zone, room, rack)
Use rackname for simplicity when available
Include gen2 parameter when dealing with Gen2 architecture racks

Troubleshooting

Common Issues

"Invalid request Parameters" Error
Cause: Missing required rack identification parameters
Solution: Provide either rackname or all four components
"File already exists" Error
Cause: Attempting POST when file exists in GitHub
Solution: Use PATCH method to update existing file
Job Stuck in "pending" Status
Cause: RQ worker issues or high queue backlog
Solution: Check RQ worker status and queue depth
GitHub API Failures
Cause: Invalid token, rate limiting, or repository permissions
Solution: Verify GitHub configuration and token permissions
Missing Global Fields Validation
- Cause: The API requires all four global fields (fzone, qzone, room, rackid) to be present in the request payload.
- Solution: Ensure all four global fields are included in the global object of your request payload.
Asynchronous Job Processing
Cause: The API returns immediately with a job ID, but the actual RIF generation happens asynchronously. Users need to poll the job status separately. --Solution Use the returned job_id to query the job status API endpoint to check completion and retrieve results.

Default Values

Field-Level Defaults

Field	Default Value	Type	Description
`host_ip`	`1.1.1.1`	IP Address	Unable to generate IP address
`bmc_host`	`1.1.1.1`	IP Address	Unable to generate IP address
`fp_host`	`1.1.1.1`	IP Address	PrimaryIPv4 not available
`fp2_ip`	`1.1.1.1`	IP Address	Unable to generate IP address
`edge`	`false`	boolean	Indicates if server is an edge server
`enclosure`	`null`	string/null	Enclosure identifier when not applicable
`enclosure_netaddress`	`null`	string/null	Network address when enclosure not used
`gpu_ident`	`""` (empty string)	string	GPU identifier when no GPU present
`min_u_position`	`""` (empty string)	string	Minimum U position when not specified
`sub_u_position`	`""` (empty string)	string	Sub U position when not applicable
`pcap_max`	`0`	integer	Maximum power cap when not configured
`pcap_min`	`0`	integer	Minimum power cap when not configured
`pcap_max_encl`	`0`	integer	Maximum enclosure power cap when not configured
`pcap_min_encl`	`0`	integer	Minimum enclosure power cap when not configured

Array Field Defaults

Field	Default Value	Description
`fp_mac`	`[]` (empty array)	FP MAC addresses when none configured
`netbox_interface`	`[]` (empty array)	Network interfaces when none defined
`solid_state_device`	`[]` (empty array)	SSD devices when none present

Debugging

Check job logs for detailed error information
Verify GitHub repository structure and permissions
Monitor RQ worker logs for background task issues
Validate input parameters against expected format