Understand REST - by exploring a working RESTful API

(New version - 1.1 - of the resource published 6th August 2020)

This resource is part of the Computer Science from the Metal Up series.

When I started teaching A-level, I was both shocked and delighted that the (AQA) spec included REST. This is a bang-up-to-date idea, but also one that is hard to grasp.

The textbooks don't help much: Heathcote on REST is, frankly, appalling; Bond is better, with clearer examples, but still perpetrates some dangerously misleading ideas, such as that Http methods are 'actions', corresponding (approximately) to CRUD actions on a database. They are not actions ('methods' is an unfortunate term - they are not like methods on an object) - GET, PUT, POST & DELETE (not a complete list) are just metadata about a resource (specified by a URL). This misconception arises because the taught examples typically portray resources as data, in which case the Http method may be used to allow the same resource to offer more than one action (e.g. CRUD). But in a real system many of the resources will in fact be actions, not data, and the method provides advance warning about the nature/consequences of accessing that resource - for example that it is 'side-effect free' (GET), idempotent (PUT), ...

The best way to grasp all this stuff is to explore a real, working, RESTful API. Accordingly, I have created a RESTful API and hosted it publicly in the cloud, along with a user interface (using a bang-up-to-date architecture - Single Page Application - written in TypeScript on top of Angular - though you don't need to know any of that). Please note that due to hosting on Azure (not the way the app is written), your first a access to the app or API may be slow, but it will speed up significantly as you start using it.

The attached Student Workbook provides a step-by-step guide to exploring first the App and then the RESTful API, and includes some surprising revelations - such as that the URL you see at the top of your browser is not necessarily anything to do with the URL on the server. Confusing, but important to understand.

This resource goes well beyond what pupils strictly need to know for the exam, but the intent is to give them a real understanding of what REST means, and why it is significant - not just to enable them to recite a few barely-understood facts. If you think it is too detailed then you could consider using the worksheet yourself as a teacher, to improve your own understanding of REST.

Unfortunately, as with too many aspects of Computer Science, the terminology applied too liberally: many systems described as RESTful do not deserve the name. The term REST was coined by Roy Fielding, one of the architects of HTTP, and hence of the world-wide web, in his PhD thesis. His definition remains the most rigorous. In an attempt to bring some clarity, Leonard Richardson classified systems that might claim to be RESTful into one of four levels (0 to 3), according to how completely they implemented the idea: with only level 3 fully matching the ideal. You may rest assured (pardon the pun!) that the API explored in this worksheet fulfils level 3 of the Richardson Maturity Model, and is fully compliant with Fielding’s definition.

The exercise does not require you to download or run any code - the app and API are online. However, as the workbook instructs, you will need to add a couple of free plug-ins to Chrome (or equivalent) in order to explore the RESTful API intelligibly.

For those interested in going any deeper, I would be happy to share with you the full C# code for the API, so that you can run it locally, and even extend/modify the domain model and its behaviours - easier than you might think. (The App is generic - it will automatically cope with changes to the API!) . The domain model actually has far more behaviour in than I can expose in the publicly-hosted version used for the worksheet, and you could enable far more functionality if you ran it privately. For obvious security/privacy reasons I can't have the publicly-hosted version allowing data to be added/modified. It would be easy for me to add security, but exploring a RESTful API directly via a browser when it has enforced security is painfully hard work. Email me if you would like the code.

Level: A-Level

Teaches:

• REST & RESTful API
• Http methods
• JSON vs XML
• Single Page Application (SPA) architecture