This service uses Google OR-Tools to create valid course schedule for multiple curricula given various constraints.
Currently, the API exposes two endpoints:
- POST
/sched
- main endpoint used for scheduling courses. Data has to be supplied in the body in JSON format. Example request body is provided in examples/example_sched_request.json. - GET
/version
- API version. Mainly used to quickly test whether API is reachable or if authentication works.
The service API can be invoked only by authenticated users. Here are some strategies on how to use the API when developing locally and when in production.
- Ensure that you have gcloud installed.
- Login:
gcloud auth login
- Ensure that you have Docker installed and that it is working properly.
- Configure Docker with gcloud:
gcloud auth configure-docker
- Get
$SHORT_SHA
of the latest commit to this repo (alphanumeric string of length 7 close to the bottom of the linked page). - Pull Docker image and run it:
PORT=8080 && docker run -p 9090:${PORT} -e PORT=${PORT} gcr.io/spare-ab/course-sched:$SHORT_SHA
/version
endpoint:
curl localhost:9090/version
/sched
endpoint:
curl -X POST -H "Content-type: application/json" --data "@examples/example_sched_request.json" localhost:9090/sched
- Ensure that you have gcloud installed.
- Login:
gcloud auth login
. - Assuming your user account has
Cloud Run Invoker
role, you can use your identity token to authenticate.
/version
endpoint:
curl -i -H "Authorization: Bearer $(gcloud auth print-identity-token)" https://course-sched-6jwajnedta-uc.a.run.app/version
/sched
endpoint:
curl -i -X POST -H "Authorization: Bearer $(gcloud auth print-identity-token)" -H "Content-type: application/json" --data "@examples/example_sched_request.json" https://course-sched-6jwajnedta-uc.a.run.app/sched
- Clone this repo.
- Follow the steps in Development section on initial setup, envvars and running API locally.
- Invoke API like in Docker image case.
Course scheduler API can be invoked by service account that App Engine uses.
/version
endpoint:
const request = require('request-promise');
const receivingServiceURL = 'https://course-sched-6jwajnedta-uc.a.run.app/sched'
// Set up metadata server request
// See https://cloud.google.com/compute/docs/instances/verifying-instance-identity#request_signature
const metadataServerTokenURL = 'http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience=';
const tokenRequestOptions = {
uri: metadataServerTokenURL + receivingServiceURL,
headers: {
'Metadata-Flavor': 'Google'
}
};
// Fetch the token, then provide the token in the request to the receiving service
request(tokenRequestOptions)
.then((token) => {
return request(receivingServiceURL).auth(null, null, true, token)
})
.then((response) => {
console.log(response);
})
.catch((error) => {
console.log(error);
});
/sched
endpoint:
var fs = require('fs');
const request = require('request-promise');
const receivingServiceURL = 'https://course-sched-6jwajnedta-uc.a.run.app/sched'
// Set up metadata server request
// See https://cloud.google.com/compute/docs/instances/verifying-instance-identity#request_signature
const metadataServerTokenURL = 'http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience=';
const tokenRequestOptions = {
uri: metadataServerTokenURL + receivingServiceURL,
headers: {
'Metadata-Flavor': 'Google'
}
};
// Fetch the token, then provide the token in the request to the receiving service
request(tokenRequestOptions)
.then((token) => {
const options = {
method: 'POST',
uri: receivingServiceURL,
body: JSON.parse(fs.readFileSync('examples/example_sched_request.json', 'utf8')),
json: true
};
return request(options).auth(null, null, true, token)
})
.then((response) => {
console.log(response);
})
.catch((error) => {
console.log(error);
});
See more at Authenticating service-to-service.
See course scheduler documentation to learn how the scheduler works.
It's best to use a virtual environment when installing dependencies for this project (e.g. virtualenv
):
- Install
virtualenv
globally:
pip install virtualenv
- Create virtual environment in the root directory of the project:
virtualenv venv
This step creates the directory venv
containing the virtual environment.
- Activate virtual enviornment:
source ./venv/bin/activate
Any Python packages installed from now on are installed just for the virtual environment and are available only when the virtual environment is activated.
- Install dependencies:
pip install -r requirements.txt
You can deactivate the virtual environment by entering deactivate
.
To remove the virtual environment, simply remove the directory venv
that was created in step 2.
Create .env
file in the root with the following contents:
PERIODS_PER_DAY=27
API_MAX_N_SOLUTIONS=999
DAYS_PER_WEEK=5
unittest
is used for testing. Run tests using:
make test
Run the command-line version of the scheduler using:
make run-sched
Run API locally with:
make run-api
Sometimes the following error is raised when initializing the scheduler model.
ImportError: cannot import name '_message' from 'google.protobuf.pyext' (.../venv/lib/python3.7/site-packages/google/protobuf/pyext/__init__.py)
Reinstall protobuf
:
pip install --upgrade --force-reinstall protobuf