Information about the Show My Homework API

smh-api.md

Show My Homework API

---

File detailing what I've worked out so far from investigating the Show My Homework API.

API Requests

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.

Known API Resources

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 have been doing some digging of my own, and I have figured out how logging in works.

Login

The requests are sent to https://api.showmyhomework.co.uk/oauth/token?client_id={1}&client_secret={2}

{1} is the client id:
The id used on the web is "55283c8c45d97ffd88eb9f87e13f390675c75d22b4f2085f43b0d7355c1f"
The id used in the app is "a44486a71714841f51744b66582427f2c094e48675b40530341d470c26d63bbd"

{2} is the client secret:
The secret used on the web is "c8f7d8fcd0746adc50278bc89ed6f004402acbbf4335d3cb12d6ac6497d3"
The secret used on mobile is "243a91065893d1e701d7f5d4ddf6d564a0e0559dfe872e6e6dfba849440af81d"

Some form data is also required:

When first logging in

form data:

username: your username
password: your password

return info:

token_type: your token type, always seems to be "bearer"
expires_in: time until "grant_type: refresh_token" must be used
refresh_token: used for refreshing your access token, see below
created_at: time of token creation
user_id: your user id
school_id: school id
user_type: type of user you are
smhw_token": another personal access token, always ends with ==

When refreshing token

This must be used when your token expires

refresh_token: refresh_token from using "grant_type: password"

return info:

Same as "grant_type: password"

Pages that require auth

'Authorization' must be passed in as a header, with the data as:
'Bearer ' + {smhw_token}

Logout

AFAIK logging out can't be invoked by a url, but I have found the function that is run when you click logout

invalidateSession: function invalidateSession() {
        var _this = this;

        var currentSchool = getOwner(this).lookup('service:current-school');
        var redirectUrl = _smhwFrontendConfigEnvironment['default'].loginURL + '?subdomain=' + currentSchool.get('subdomain');
        this.get('session').invalidate().then(function () {
          _this.get('mixpanelTracker').resetSuperProperties();
          _this.get('mixpanelTracker').reset();
          document.location.href = redirectUrl;
        })['catch'](console.log.bind(console));
      }

@ZingBallyhoo nice, you may be interested in this repo, I'm aiming to build a command line tool for working with SMH calendars.

@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.

@abactel That's pretty cool! I've watched your repo, I'll be interested to see how it progresses (and perhaps steal some ideas :))

Any idea where the normal oauth endpoint is that you would use in a web app for example? Im trying to get an app to have the user login using their credentials the same way you would login to twitter using oath.

https://www.showmyhomework.com/oauth2 and https://www.showmyhomework.com/oauth2 and even when sending all the oauth secret and client id they 404

Can someone confirm this still works? Getting 404 using the basic example provided above

@JellyWX No I don't think this works anymore. It is still possible to use the icalendar functionality built into smhw to access a homework list but the other stuff is gone.

Don't know what changed, but I can confirm this currently works. Just used it to pull a load of information about my school

Thought I'd post this Python library and this C++ library here. Both are still in development (the C++ one doesn't actually build yet) but it's on the way.

I've been trying to find a good way to search for a school's subdomain from its name, but no luck. For some schools, it's on their site, but not all sites have it posted, and just running https://api.showmyhomework.co.uk/api/schools doesn't list all schools, so you can't look through there. One thing I noticed is that after you log out on the main site, it passes a parameter on the login screen for the domain so that you can easily login to the same school again, so it may be possible to use that to find a way for it to pass that parameter even if you can't login successfully, then search using the login page drop down box. The name shown in the drop-down is that name shown in the API.

If anyone still wants a node solution for this, I made this: https://github.com/edqx/node-smhw
It features quite a lot of the api from what I could gather, I use jsdoc for the documentation which is at https://smhw.thechimp.store

Any information on a python solution that still works?

@OskarZyg
@fourohfour

Hello! I'm pretty late to the party but here is an updated version of everything I could find, really easy to use :)

smhw API docs updated, working from 18/03/21

👍 This is great, thanks a lot!

The gist does not seem to be up anymore so I have created my own python interface for it: https://github.com/EpicGamerCodes/smhw-api

That looks amazing- I wish it was there earlier. Hopefully, my new college uses SMHW too so I can make use of it :p