Districts Management
Table of Contents
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.
{
"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"
}
]
}
// 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.
{
"status": "OK",
"message": "Districts fetched successfully",
"district_id": "103",
"district_name": "Lewisville ISD"
}
// 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.
{
"status": "OK",
"message": "District added successfully",
"district_id": "103"
}
// 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.
{
"status": "OK",
"message": "District updated successfully"
}
// 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.
{
"status": "OK",
"message": "District removed successfully"
}
// 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.
// 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();
*/