UCL API started as a student-built platform for student developers to improve the student experience of everyone at UCL. We now also have our own end-user facing applications in addition to this, such as UCL Assistant, our rival app to UCL GO.

Create a ridiculously simple, documentation first, and comprehensive API around UCL's digital services and establish an ecosystem of third party UCL apps and services that use the API. Find out more at our website or if you feel brave try staging.

Read on more to find out how to setup and build the API. From here you can start writing your own changes and submitting them. See our Contribution Guide to learn more about how you can contribute.

For this setup to work you need to have docker, git, python (3.7), and node + pnpm installed. If you would like the old setup guide (without docker) that can be found here, it also contains some advanced information for maintainers. This guide has been tested to work on Windows (we recommend PowerShell Core), Linux, and MacOS.

Clone uclapi to a local directory:

git clone https://github.com/uclapi/uclapi.git
cd uclapi

Then start the development docker compose file:

docker-compose -f docker-compose-dev.yml up

And setup the frontend:

cd uclapi-frontend
pnpm install
pnpm start

And setup your Python virtual environment & Django (you may need to write python instead of python3):

cd backend/uclapi
cp .env.docker.example .env
python3 -m venv ./venv

# For unix:
source ./venv/bin/activate
# For windows:
./venv/Scripts/activate

# Then
pip install -r requirements.txt

# Finally, start the Django web server:
cd backend/uclapi
python3 manage.py runserver

If those commands work you should be able to navigate to http://localhost:8000/dashboard in your browser, which will let you log in via Azure AD. If so, then you're up and running!

We're an amazing project, so obviously we have tests ✨. Make sure you have the requirements installed in your virtual environment (and you have activated it) , cd into backend/uclapi and then run : python manage.py test --settings=uclapi.settings_mocked

We have a pre-commit hook set up that runs eslint on all staged JS files, stylelint on all staged scss files, and autopep8 & flake8 on all staged Python files. This automatically fixes style issues and stops the commit if there are any obvious problems (e.g. failure to define variable).

As well as the user-facing documentation we also now ship our own internal Documentation which aims to help developers contribute to our code. To make it simply run make html while in the backend directory. You can then navigate to the build directory and open up index.html in your favourite browser to view the documentation. It can also be built in pdf, latex and a few other formats.