Schools Management
Table of Contents
Overview
Schools are organizational units within districts in the RCAMS hierarchy. Each school can contain multiple groups and light devices. This section details the API endpoints for managing schools, including listing, creating, updating, and deleting schools.
Note: All school management endpoints require basic authentication. The user must have appropriate permissions for the requested operations.
School Management API Endpoints
| Operation | Endpoint | Action Parameter |
|---|---|---|
| List Schools | /school.php |
list |
| Get School | /school.php |
get |
| Create School | /school.php |
insert |
| Update School | /school.php |
update |
| Delete School | /school.php |
remove |
List Schools
Retrieves all schools within a district.
POST/school.php
Returns a list of all schools within the specified district.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
action |
String | Yes | Must be set to list |
district_id |
String | Yes | ID of the district to list schools from |
Response
Returns a list of schools with their details.
{
"status": "OK",
"message": "Client found",
"total": 6,
"school_list": [
{
"school_id": 1,
"school_name": "Grand Prairie High School",
"school_phone": null,
"school_email": null,
"school_address": null,
"district_id": 1,
"school_status": "enable"
},
{
"school_id": 3,
"school_name": "Dubiski Career High School",
"school_phone": null,
"school_email": null,
"school_address": null,
"district_id": 1,
"school_status": "enable"
},
{
"school_id": 6,
"school_name": "Test Client Insert",
"school_phone": "999-777-8888",
"school_email": "newclient@testclient.con.us",
"school_address": "new test address",
"district_id": 1,
"school_status": "enable"
}
]
}
// Set up the request
const jsonData = JSON.stringify({
action: 'list',
district_id: '1'
});
// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/school.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(`Found ${data.total} schools:`, data.school_list);
} else {
console.error('Error:', data.message);
}
})
.catch(error => console.error('Error:', error));
Get School
Retrieves details for a specific school.
POST/school.php
Returns detailed information about a specific school.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
action |
String | Yes | Must be set to get |
school_id |
String | Yes | ID of the school to retrieve |
Response
Returns the details of the specified school.
{
"status": "OK",
"message": "Client found",
"school_id": 1,
"school_name": "Grand Prairie High School",
"school_phone": null,
"school_email": null,
"school_address": null,
"district_id": 1,
"school_status": "enable"
}
// Set up the request
const jsonData = JSON.stringify({
action: 'get',
school_id: '1'
});
// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/school.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('School details:', data);
} else {
console.error('Error:', data.message);
}
})
.catch(error => console.error('Error:', error));
Create School
Creates a new school within a district.
POST/school.php
Creates a new school with the specified details.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
action |
String | Yes | Must be set to insert |
district_id |
String | Yes | ID of the district to add the school to |
school_name |
String | Yes | Name of the new school |
school_phone |
String | No | Phone number for the school |
school_email |
String | No | Email address for the school |
school_address |
String | No | Physical address of the school |
Response
Returns confirmation that the school was created and provides the new school ID.
{
"status": "OK",
"message": "Client added successfully",
"school_id": "9"
}
// Set up the request
const jsonData = JSON.stringify({
action: 'insert',
district_id: '1',
school_name: 'Jefferson Middle School',
school_phone: '(123) 456-7890',
school_email: 'info@jefferson.edu'
school_address: '123 Education Blvd'
});
// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/school.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('School created with ID:', data.school_id);
} else {
console.error('Error:', data.message);
}
})
.catch(error => console.error('Error:', error));
Update School
Updates an existing school's information.
POST/school.php
Updates the details of an existing school.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
action |
String | Yes | Must be set to update |
school_id |
String | Yes | ID of the school to update |
district_id |
String | Yes | ID of the district the school belongs to |
school_name |
String | Yes | Updated name for the school |
school_phone |
String | No | Updated phone number |
school_email |
String | No | Updated email address |
school_address |
String | No | Updated physical address |
Response
Returns confirmation that the school was updated.
{
"status": "OK",
"message": "Client updated successfully"
}
// Set up the request
const jsonData = JSON.stringify({
action: 'update',
school_id: '9',
district_id: '1',
school_name: 'Jefferson STEM Middle School',
school_phone: '(123) 456-7890',
school_phone: 'info@jefferson.edu',
school_address: '123 Education Blvd'
});
// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/school.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('School updated successfully');
} else {
console.error('Error:', data.message);
}
})
.catch(error => console.error('Error:', error));
Delete School
Removes a school from the system.
Warning: Deleting a school will remove all associated groups and light assignments. This action cannot be undone.
POST/school.php
Deletes a school from the system.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
action |
String | Yes | Must be set to remove |
school_id |
String | Yes | ID of the school to delete |
Response
Returns confirmation that the school was deleted.
{
"status": "OK",
"message": "Client removed successfully"
}
// Set up the request
const jsonData = JSON.stringify({
action: 'remove',
school_id: '9'
});
// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/school.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('School removed successfully');
} else {
console.error('Error:', data.message);
}
})
.catch(error => console.error('Error:', error));
Code Examples
School Management Example
The following example demonstrates a complete flow for school management, including listing, creating, updating, and deleting schools.
// 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 json = {};
for (const [key, value] of Object.entries(params)) {
json[key] = value;
}
const jsonString = JSON.stringify(json);
try {
const response = await fetch(`https://rcamsapi.spheronomics.com/api/v2/${endpoint}`, {
method: 'POST',
headers: {
'Authorization': 'Basic ' + btoa(`${apiUsername}:${apiPassword}`)
},
body: jsonString
});
return await response.json();
} catch (error) {
console.error('API request failed:', error);
throw error;
}
}
// Example usage - School Management
async function schoolManagementExample( districtId) {
try {
// 1. List all schools in the district
console.log(`Listing all schools in district ${districtId}...`);
const listResponse = await makeApiRequest('school.php', {
action: 'list',
district_id: districtId
});
console.log(`Found ${listResponse.total} schools:`, listResponse.school_list);
// 2. Create a new school
console.log('Creating a new school...');
const createResponse = await makeApiRequest('school.php', {
action: 'insert',
district_id: districtId,
school_name: 'Example Elementary School',
school_phone: '(555) 123-4567',
school_email: 'info@example-school.edu',
school_address: '789 Learning Lane'
});
if (createResponse.status === 'OK') {
const newSchoolId = createResponse.school_id;
console.log(`Created school with ID: ${newSchoolId}`);
// 3. Get the school details
console.log('Getting school details...');
const getResponse = await makeApiRequest('school.php', {
action: 'get',
school_id: newSchoolId
});
console.log('School details:', getResponse);
// 4. Update the school information
console.log('Updating school information...');
const updateResponse = await makeApiRequest('school.php', {
action: 'update',
school_id: newSchoolId,
district_id: districtId,
school_name: 'Updated Elementary School',
school_phone: '(555) 123-9876',
school_email: 'updated@example-school.edu',
school_address: '789 Learning Lane Suite 101'
});
console.log('Update result:', updateResponse.message);
// 5. Delete the school (commented out for safety)
// Uncomment to actually delete the school
/*
console.log('Deleting school...');
const deleteResponse = await makeApiRequest('school.php', {
action: 'remove',
school_id: newSchoolId
});
console.log('Delete result:', deleteResponse.message);
*/
}
} catch (error) {
console.error('An error occurred:', error);
}
}
// Run the example (you would need a valid district ID)
/*
async function runExample() {
const loginResponse = await makeApiRequest('login.php', {
user: 'user@example.com',
pass: 'password123'
});
if (loginResponse.status === 'OK') {
await schoolManagementExample( '1'); // Replace '1' with actual district ID
} else {
console.error('Login failed:', loginResponse.message);
}
}
runExample();
*/