ritherdon-rest/README.md

# Ritherdon REST

## Note: The REST API is no longer active

The server hosting the REST API this code calls out to is no longer activer. This means the code in this repository no longer works. I have decided to archive the project so the code can still be referenced.

## About this Project

This is a Common Lisp system 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.