File detailing what I've worked out so far from investigating the Show My Homework API.
API requests are made in the form of a HTTPS GET request to the SMH API endpoint.
https://api.showmyhomework.co.uk/api/{request}
The payload of the response will be a JSON object containing the requested data, as with most standard REST APIs.
For the request to be accepted the HTTP header field Accept must be set to the value application/smhw.v3+json. If this is not done, a standard 'Page not found' web-page is returned instead.
Here's an example implementation for an API access using Python 3 and the requests module.
import requests
response = requests.get("https://api.showmyhomework.co.uk/api/employees?school_id=1337",
headers = {"Accept" : "application/smhw.v3+json"})
print(response.text)
This prints a JSON file containing the information for all employees at the school with the id 1337.
API Resources follow the following scheme:
/{resource name}?{a1 name}={a1 value}&{a2 name}={a2 value}...
a1 is the first argument of the request
a2 is the second argument of the request
Like with all URLs, additional arguments can be added with an ampersand (&).
Generally, resources have mandatory arguments, such as school_id or subdomain, which must not be omitted. Often, additional arguments can be supplied to filter the result set down as necessary.
This list is not known to be complete. It is simply a list of known resources found by analysing HTTP headers which are sent when SMH webpages are loaded.
/schools
This resource gets a list of schools within a subdomain - although usually a subdomain will only contain a single school.
The scheme is given below.
/schools?subdomain={1}
{1} is the subdomain as a string (i.e. for myschool.showmyhomework.co.uk the subdomain is myschool)
Interestingly, the subdomain is not actually a required argument, and omitting it results in a number of seemingly random schools being returned, which is not particuarly helpful for anything.
/subjects
This resource gets a list of subjects at a school. Pretty self explanatory, really! The scheme is given below.
/subjects?school_id={1}
{1} is the ID of the school in question
/employees
This resource gets information on all employees at a school. The scheme for it is given below
/employees?school_id={1}
{1} is the ID of the school in question
/class_years
This resource gives a list of years into which classes can fall (i.e Year 7, Year 8, Year 9 etc.)
The scheme for it is as follows
/class_years?school_id={1}
{1} is the ID of the school in question
/class_groups
This resource gives a list of classes within a school.
/calendars?school_id={1}
{1} is the ID of the school in question
/calendars
This resource gets a list of calendar entries (i.e. overviews of homework pieces) that match the given criteria.
The scheme for it is as follows
/calendars?subdomain={1}
{1} is the subdomain as a string (i.e. for myschool.showmyhomework.co.uk the subdomain is myschool)
This request yields a lot of data. It is highly recommended that further arguments are provided to filter down the results, for example giving a date:
date=YYYY-MM-DD
@fourohfour I didn't realize you were already working on that, so I did a really similar thing 😑 . You might want to take a look at my repo, I'm trying to create a range of methods to communicate smhw. Once I'm done there'll be a core module that should be usable in other projects.