Districts Management

Overview

Districts are the top-level organizational units in the RCAMS hierarchy. This section details the API endpoints for managing districts, including listing, creating, updating, and deleting districts.

Note: All district management endpoints require both basic authentication. The user must have appropriate permissions for the requested operations.

District Management API Endpoints
Operation Endpoint Action Parameter
List Districts /district.php list
Get District /district.php get
Create District /district.php insert
Update District /district.php update
Delete District /district.php remove

List Districts

Retrieves all districts accessible to the authenticated user.

POST/district.php

Returns a list of all districts the user has access to view.

Request Parameters
Parameter Type Required Description
action String Yes Must be set to list
Response

Returns a list of districts with their IDs and names.

Example Response
{
  "status": "OK",
  "message": "Districts found",
  "districts": [
    {
      "district_id": "1",
      "district_name": "Lewisville ISD"
    },
    {
      "district_id": "2",
      "district_name": "Houston ISD"
    },
    {
      "district_id": "3",
      "district_name": "Grand Prairie ISD"
    }
  ]
}
Example Request (JavaScript)
// Set up the request
const jsonData = JSON.stringify({
    action: 'list'
});

// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/district.php', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('api_username:api_password')
  },
  body: jsonData
})
.then(response => response.json())
.then(data => {
  if (data.status === 'OK') {
    console.log('Districts:', data.districts);
  } else {
    console.error('Error:', data.message);
  }
})
.catch(error => console.error('Error:', error));

Get District

Retrieves details for a specific district.

POST/district.php

Returns detailed information about a specific district.

Request Parameters
Parameter Type Required Description
action String Yes Must be set to get
district_id String Yes ID of the district to retrieve
Response

Returns the details of the specified district.

Example Response
{
  "status": "OK",
  "message": "Districts fetched successfully",
  "district_id": "103",
  "district_name": "Lewisville ISD"
}
Example Request (JavaScript)
// Set up the request
const jsonData = JSON.stringify({
    action: 'get',
    district_id: '103'
});

// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/district.php', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('api_username:api_password')
  },
  body: jsonData
})
.then(response => response.json())
.then(data => {
  if (data.status === 'OK') {
    console.log('District ID:', data.district_id);
    console.log('District Name:', data.district_name);
  } else {
    console.error('Error:', data.message);
  }
})
.catch(error => console.error('Error:', error));

Create District

Creates a new district in the system.

POST/district.php

Creates a new district with the specified name.

Request Parameters
Parameter Type Required Description
action String Yes Must be set to insert
district_name String Yes Name of the new district
Response

Returns confirmation that the district was created and provides the new district ID.

Example Response
{
  "status": "OK",
  "message": "District added successfully",
  "district_id": "103"
}
Example Request (JavaScript)
// Set up the request
const jsonData = JSON.stringify({
    action: 'insert',
    district_name: 'South Ridge School District'
});

// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/district.php', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('api_username:api_password')
  },
  body: jsonData
})
.then(response => response.json())
.then(data => {
  if (data.status === 'OK') {
    console.log('District created with ID:', data.district_id);
  } else {
    console.error('Error:', data.message);
  }
})
.catch(error => console.error('Error:', error));

Update District

Updates an existing district's information.

POST/district.php

Updates the name of an existing district.

Request Parameters
Parameter Type Required Description
action String Yes Must be set to update
district_id String Yes ID of the district to update
district_name String Yes New name for the district
Response

Returns confirmation that the district was updated.

Example Response
{
  "status": "OK",
  "message": "District updated successfully"
}
Example Request (JavaScript)
// Set up the request
const jsonData = JSON.stringify({
    action: 'update',
    district_id: '103',
    district_name: 'South Ridge Unified School District'
});

// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/district.php', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('api_username:api_password')
  },
  body: jsonData
})
.then(response => response.json())
.then(data => {
  if (data.status === 'OK') {
    console.log('District updated successfully');
  } else {
    console.error('Error:', data.message);
  }
})
.catch(error => console.error('Error:', error));

Delete District

Removes a district from the system.

Warning: Deleting a district will remove all associated schools, groups, and light assignments. This action cannot be undone.

POST/district.php

Deletes a district from the system.

Request Parameters
Parameter Type Required Description
action String Yes Must be set to remove
district_id String Yes ID of the district to delete
Response

Returns confirmation that the district was deleted.

Example Response
{
  "status": "OK",
  "message": "District removed successfully"
}
Example Request (JavaScript)
// Set up the request
const jsonData = JSON.stringify({
    action: 'remove',
    district_id: '103'
});

// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/district.php', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('api_username:api_password')
  },
  body: jsonData
})
.then(response => response.json())
.then(data => {
  if (data.status === 'OK') {
    console.log('District removed successfully');
  } else {
    console.error('Error:', data.message);
  }
})
.catch(error => console.error('Error:', error));

Code Examples

District Management Example

The following example demonstrates a complete flow for district management, including listing, creating, updating, and deleting districts.

Complete District Management Example (JavaScript)
// Helper function for API requests
async function makeApiRequest(endpoint, params) {
  // API credentials - replace with actual values
  const apiUsername = 'your_api_username';
  const apiPassword = 'your_api_password';
  
  // Create form data from params
  const formData = new FormData();
  for (const [key, value] of Object.entries(params)) {
    formData.append(key, value);
  }
  
  // Convert form data to JSON
  const jsonData = JSON.stringify(Object.fromEntries(formData));

  try {
    const response = await fetch(`https://rcamsapi.spheronomics.com/api/v2/${endpoint}`, {
      method: 'POST',
      headers: {
        'Authorization': 'Basic ' + btoa(`${apiUsername}:${apiPassword}`)
      },
      body: jsonData
    });
    
    return await response.json();
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}

// Example usage - District Management
async function districtManagementExample() {
  try {
    // 1. List all districts
    console.log('Listing all districts...');
    const listResponse = await makeApiRequest('district.php', {
      action: 'list'
    });
    
    console.log(`Found ${listResponse.districts.length} districts:`, listResponse.districts);
    
    // 2. Create a new district
    console.log('Creating a new district...');
    const createResponse = await makeApiRequest('district.php', {
      action: 'insert',      
      district_name: 'Example School District'
    });
    
    if (createResponse.status === 'OK') {
      const newDistrictId = createResponse.district_id;
      console.log(`Created district with ID: ${newDistrictId}`);
      
      // 3. Get the district details
      console.log('Getting district details...');
      const getResponse = await makeApiRequest('district.php', {
        action: 'get',
        district_id: newDistrictId
      });
      
      console.log('District details:', getResponse);
      
      // 4. Update the district name
      console.log('Updating district name...');
      const updateResponse = await makeApiRequest('district.php', {
        action: 'update',
        district_id: newDistrictId,
        district_name: 'Updated Example School District'
      });
      
      console.log('Update result:', updateResponse.message);
      
      // 5. Delete the district (commented out for safety)
      // Uncomment to actually delete the district
      /*
      console.log('Deleting district...');
      const deleteResponse = await makeApiRequest('district.php', {
        action: 'remove',
        district_id: newDistrictId
      });
      
      console.log('Delete result:', deleteResponse.message);
      */
    }
  } catch (error) {
    console.error('An error occurred:', error);
  }
}

async function runExample() {
  const loginResponse = await makeApiRequest('login.php', {
    user: 'user@example.com',
    pass: 'password123'
  });
  
  if (loginResponse.status === 'OK') {
    await districtManagementExample();
  } else {
    console.error('Login failed:', loginResponse.message);
  }
}

runExample();
*/