Ritherdon REST

A package which grabs data from the Return to Ritherdon project's REST API server.

The intended way to use this code is within a Lisp REPL -- something like SLIME in Emacs or Steel Bank Common Lisp (SBCL). If they do not mean anything to you, this code is probably not for you (or this repo. is a little early in your learning of Common Lisp).

The code makes HTTP Requests from the Return to Ritherdon API and parses the returned JSON data. I expect this API to close down in the later stages of 2021 when the No Gaps in the Line exhibition ends. The code in this repository will remain as reference material, though (I'm using this to learn Common Lisp).

The project's file structure is,

ritherdon-rest/
├── LICENSE
├── README.md
├── ritherdon-rest.asd
├── src
│   ├── package.lisp
│   └── ritherdon-rest.lisp
└── tests
    ├── main.lisp
    └── package.lisp

2 directories, 7 files

If you just want to jump straight into the code, head to /src/ritherdon-rest.lisp.

/src is the project with the code to make requests and parse the data returned from those requests. /tests is the testing suite for the code in /src. The ritherdon-rest.asd file provides code for ASDF and summaries how the two systems/packages connect to each other. Again, if this meaning nothing to you, this might be a little early in your Common Lisp learning.

There are two ways to use this code:

• Quicklisp
• ASDF

Note on Passing URL Arguments into The System

The code already has the base-URL stored in it. So you only need to pass in the specific part of the API call you want to make. For example, the full URL to get the latest status logs for all the devices is http://ritherdon.abbether.net/api/status/latest. But, the part specific to this request is /status/latest. So, this is the part you need to pass in. Other examples are,

• http://ritherdon.abbether.net/api/status/latest/1 becomes /status/latest/1
• http://ritherdon.abbether.net/api/readings/latest/2 becomes /readings/latest/2
• http://ritherdon.abbether.net/api/readings/all/2 becomes /readings/all/2

The full list of API calls available are at Return to Ritherdon API.

Use with Quicklisp

I tend to sym-link this project into the /local-projects folder, so this step might be unnecessary for you. I am keeping it here to jog the memory of those who prefer to have their code in a place outside /local-projects -- hopefully catch it early and avoid any unnecessary error message.

# Adjust the paths accordingly.
ln -s ~/dev-folder/ritherdon-rest ~/quicklisp/local-projects

When the project is in there, either start SBCL (CLI) or SLIME (Emacs) and load the system into it,

(ql:quickload :ritherdon-rest)

;;; From there, I can start using it.
(ritherdon-rest:parse-request "/status/latest")

To run the tests, you need to Quickload the ritherdon-rest/test package,

(ql:quickload :ritherdon-rest/tests)

;;; You might get a naming conflict with FiveAM and Ratify. SBCL or
;;; SLIME with provide you with options to resolve the naming
;;; conflict. This is a bit inconsistent for me so I can't give exact
;;; instructions. Although, I found prioritising the FiveAM package's use
;;; of `TEST' works best.

;; To run the tests...
(ritherdon-rest-tests:test-quasi)

I do not tend to use Quicklisp that much so you might come across errors I have not mentioned here.

Use with ASDF

To load the system via ASDF, enter the following into SBCL or SLIME,

(asdf:load-system :ritherdon-rest)

;;; To use the code,

(ritherdon-rest:parse-request "/status/latest/1")

;;; The 'ritherdon-rest.asd' file has connected the test system to the
;;; main system. So you can run the tests from the main system. In other
;;; words, to run the tests,
(asdf:test-system :ritherdon-rest) ;Instead of ':ritherdon-rest/tests'.

If you are making repeated calls and want to reduce the amount of typing you are doing, you can jump into the ritherdon-rest package and call its functions directly.

;;; This removes the need to type the 'ritherdon-rest:' part all the time.
(in-package :ritherdon-rest)
(parse-request "/status/latest")
(parse-request "/reading/latest/2")
(parse-request "reading/all/1")

;;; To return to the default package,
(in-package :common-lisp-user)

Notes on Repository Support

This repository is to help me learn Common Lisp. Because of this, there is no Issue Tracker, Wiki or Requests section. I have made this repository public on the off-chance is might help you learning about Common Lisp by seeing something in-situ.

The Return to Ritherdon API has HTTP-Push requests. I have not provided any functions to make these types of requests because I do not want to run the risk of breaking that system. The API is part of an active art exhibition and I do not want to corrupt the data it stores/created in any way.

I have ran this project on Linux and nothing else. I have no idea if this work on Windows or MacOS. I, also, have no urge to find out. Unfortunately, you are on your own here because I have no means to test it.

As stated near the top of this document, I am expecting to shutdown the API near the end of 2021. When that happens, this will remain as a reference repository.