Welcome to the UCL API

Published in

UCL API

6 min readOct 6, 2017

Making your first requests!

Whether you’re a student at the UCL API Hackathon, or you’re reading this some time in the future, you may be wondering what this is about and how you can get going. Fear not! Over this quick ten (or so) minute tutorial I’ll throw you right into the platform with some examples to get you going.

This guide is aimed at those who have never used an API before and have very limited programming experience. If you are already an API whiz then you should hop over to the UCL API Docs and jump straight in.

What is this?

If you are new to UCL API, you may not even know why you are here. Let’s break it down, because acronyms are scary:

UCL: University College, London
The great university where you study
API: Application Programming Interface
A platform that lets you build a service on top of another service

By using UCL API you are able to write a program, website or mobile app that utilises some internal services at UCL via our platform which securely exposes this data to you. As time goes on we will be opening up more and more of what goes on behind the scenes of UCL so that you, as students or staff, can solve technical problems the way you want to. We provide the data, you provide the app to solve real world problems.

Still with us? Cool! Let’s throw you into some examples. But firstly, I’m going to make a naive assumption: you’ve written some sort of code before. My examples will be based on Python and Node.js, because people seem to like those languages, but the ideas will be portable to any language you like. C, Haskell, Java, Rust, C#, Visual Basic, COBOL, emotif___, whatever you fancy!

Getting a Token

The first place to start is the UCL API Dashboard. You will be faced with a screen that looks a bit like this:

Enter your UCL account details then hit Login. This will take you to the UCL API Dashboard.

You will initially begin without any apps there. So go ahead and click the big blue plus button. This will let you create a new app.

Give your app a useful name, then press Create. In this demo we’re going to create a new app called Rooms 4 U, which will show you all the rooms at UCL that are centrally bookable (e.g. available through the UCL Estates room bookings service).

This will add the app to your dashboard, along with a very long API Token. Your token is a private piece of information (don’t give it away!) that allows your code, which you’ll write later, to act on your behalf and request public UCL data (such as rooms and module timetables). The OAuth settings below are for if you want a user to log into your app with their UCL account to give you their private data, and webhooks are for receiving updates about new room bookings. We won’t cover that detail here.

Now that you have your API Token, which starts with uclapi-, you can move on to using it!

Making Your First Request

APIs work by using requests. Your app requests some data from the API then it responds with either what you asked for or an error message telling you why you can’t have what you asked for. UCL API will know what you want based on three things:

USEFUL NOTE: everything I describe here, and much, much more, is documented over at https://docs.uclapi.com. Feel free to adapt these examples based on those docs.

The endpoint you use
The endpoint is the web address you use to request some data, such as uclapi.com/roombookings/bookings
The parameters you supply
These are the options, such as which room you want the bookings, or which time parameters to work with
The token supplied
This is how our server knows that it is you without you having to send us your UCL username or password

Let’s take the rooms endpoint as an example. We are not going to supply any special parameters, so the request we need to make would be to https://uclapi.com/roombookings/rooms?token=your-uclapi-token-here. You’ll get a response that looks like this:

{
    "rooms": [
        {
            "roomid": "335",
            "siteid": "374",
            "sitename": "Medical School Building",
            "location": {
                "address": [
                    "74 Huntley Street",
                    "London",
                    "WC1E 6AU",
                    ""
                ],
                "coordinates": {
                    "lng": "-0.134937",
                    "lat": "51.523504"
                }
            },
            "capacity": 20,
            "classification": "CR",
            "automated": "P",
            "roomname": "Rockefeller Building 335"
        },
        {
            "roomid": "251",
            "siteid": "180",
            "sitename": "Birkbeck Malet Street",
            "location": {
                "address": [
                    "Malet Street",
                    "London",
                    "",
                    ""
                ],
                "coordinates": {
                    "lng": "-0.1305394",
                    "lat": "51.5218725"
                }
            },
            "capacity": 25,
            "classification": "CR",
            "automated": "N",
            "roomname": "Birkbeck Malet Street 251"
        },
        ...
    ]
}

The response is in a format called JSON, which allows us to write data which makes sense to humans and can really quickly be converted to useful objects in computer code. Here is a quick JSON Cheat Sheet:

[1, 2, 3, 4, 5]: Lists of items are enclosed in square brackets{"name": "Chris", Age: 20}: Dictionaries are enclosed in curly braces. Each item has a key and a value separated by a colon1: Numbers are just as istrue/false: Boolean values (yes or no, etc.)"text here!": text / strings are enclosed in double quotes

This endpoint contains every centrally bookable room at UCL. Congrats! You have some UCL API data which should make sense when you read through it.

Some Code

Now that we can get data from the API, the natural progression is to do this in code. I will give some example code in pure Python and Node.js. It should be possible to incorporate this into any project you work on.

Python

For Python we use a library called requests, which allows you to make API requests with far less code than just pure python. To install requests, open a terminal and type pip install requests to get the code installed.

Now use the following Python example to fetch some data from the API:

Example code for getting the rooms and their capacities at UCL

Note that you will have to change the token constant to your unique token. Run this with python UCLAPI-Rooms-Example.py and you should get a list on your screen of every UCL centrally bookable room with its capacity. Cool, huh?

Node.js

For Node you can make use of the Glitch project I have already put together for you! Take a look here: https://uclapi-rooms-example.glitch.me.

If you want to make your own version of this app, just click the big Remix This button below!

Click this button to remix the rooms example!

All you’ll need to add to make the example work is the following line in .env :

UCLAPI_TOKEN=uclapi-your-long-token-code-here

Then when you look at it live you should get, after a couple of seconds, a list of every centrally bookable room at UCL along with its capacity!

Conclusion

I hope you found this tutorial useful! If you have any questions about the API or any of these examples during the hackathon feel free to message me on Slack (my username is chris); alternatively, you can email me at chris [at] ucl [dot] ac [dot] uk.

Happy programming! 💖