Schools Management

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.

Example Response
{
  "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"
    }
  ]
}
Example Request (JavaScript)
// 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.

Example Response
{
  "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"
}
Example Request (JavaScript)
// 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.

Example Response
{
  "status": "OK",
  "message": "Client added successfully",
  "school_id": "9"
}
Example Request (JavaScript)
// 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.

Example Response
{
  "status": "OK",
  "message": "Client updated successfully"
}
Example Request (JavaScript)
// 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.

Example Response
{
  "status": "OK",
  "message": "Client removed successfully"
}
Example Request (JavaScript)
// 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.

Complete School 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 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();
*/