|
|
|
|
# Ritherdon REST
|
|
|
|
|
|
|
|
|
|
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.
|