From 348dbe596e33fa4d80d2362887801582f5316cf2 Mon Sep 17 00:00:00 2001 From: Craig Oates Date: Fri, 2 Jul 2021 19:47:28 +0100 Subject: [PATCH] Squash Commit of Stable into Master. --- README.md | 162 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 161 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 445c55a..8255344 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,163 @@ # Ritherdon REST -A CLI program which grabs data from the Return to Ritherdon project's REST API server. +A package which grabs data from the [Return to +Ritherdon](http://ritherdon.abbether.net/) 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](http://ritherdon.abbether.net/api/ui/) 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](https://www.castlefieldgallery.co.uk/event/nicola-ellis-solo-exhibition-coming-in-2021/) +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, + +```bash +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](https://www.quicklisp.org/beta/) +- [ASDF](https://common-lisp.net/project/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](http://ritherdon.abbether.net/api/ui/). + +## 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. + +```bash +# 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, + +```lisp +(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, + +```lisp +(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, + +```lisp +(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. + +```lisp +;;; 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](http://ritherdon.abbether.net/api/ui/) +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.