|
12 months ago | |
---|---|---|
src | 2 years ago | |
tests | 2 years ago | |
.gitignore | 2 years ago | |
LICENSE | 2 years ago | |
README.md | 12 months ago | |
ritherdon-rest.asd | 2 years ago |
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 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:
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.