Merge pull request #1 from SURFnet/apie

Rename to `apie`, remove eduhub-specific files

.github/workflows/build.yaml

@@ -93,7 +93,7 @@ jobs:
           ./lib
 
     - name: Artifact name
-      run: echo filename=eduhub-validator-${{ needs.create_release.outputs.version }}-${{ matrix.arch }} >> $GITHUB_OUTPUT
+      run: echo filename=apie-${{ needs.create_release.outputs.version }}-${{ matrix.arch }} >> $GITHUB_OUTPUT
       id: artifact
 
     - name: Install clj runtime

.gitignore

@@ -2,7 +2,6 @@
 /.envrc
 /bin/
 /lib/
-eduhub-validator*
 *.tar.gz
 /report.html
 /observations.edn

Makefile

@@ -2,7 +2,7 @@
 #
 # Expects the artifact to be in the format
 #
-#        `eduhub-validator-VERSION-ARCH.EXT
+#        `apie-VERSION-ARCH.EXT
 #
 # Where VERSION matches the current git tag (like `v0.0.1-SNAPSHOT`)
 #
@@ -13,8 +13,8 @@
 # babashka (variants of linux, windows and macos), see
 # https://github.com/babashka/babashka/releases
 #
-# In other words, `make eduhub-validator-$VERSION-windows-amd64.zip`
-# and `make eduhub-validator-$VERSION-macos-aarch64.tar.gz` will do
+# In other words, `make apie-$VERSION-windows-amd64.zip`
+# and `make apie-$VERSION-macos-aarch64.tar.gz` will do
 # what you expect as long as $VERSION is the currently tagged version
 
 BB:=bb
@@ -25,21 +25,23 @@ BABASHKA_VERSION:=1.3.186-SNAPSHOT
 
 .PHONY: uberjar
 
-exec_base_name=eduhub-validator
+exec_base_name=apie
 release_name=$(exec_base_name)-$(version)
-source_files=$(shell find src assets profiles -type f)
+source_files=$(shell find src assets -type f)
+current_arch=$(shell bb dev/current_arch.clj)
 
 # uberjar is the babashka uberjar (not a java-compatible jar)
 uberjar=$(exec_base_name)-$(version)-standalone.jar
 
 uberjar: $(uberjar)
 
 $(uberjar): deps.edn bb.edn $(source_files)
-	$(BB) uberjar $@ -m nl.jomco.eduhub-validator.main
+	$(BB) uberjar $@ -m nl.jomco.apie.main
 
 release: $(binary_release)
 
 # for unixy systems
+
 $(release_name)-%/$(exec_base_name): babashka-$(BABASHKA_VERSION)-%.tar.gz $(uberjar)
 	mkdir -p $(dir $@)
 	tar -zxO <$< >$@
@@ -64,3 +66,11 @@ $(release_name)-%.tar.gz: $(release_name)-%/$(exec_base_name)
 # for windows
 $(release_name)-%.zip: $(release_name)-%/$(exec_base_name).exe
 	zip -r $@ $(basename $@)
+
+# build for local use, on windows
+$(exec_base_name).exe: $(release_name)-$(current_arch)/$(exec_base_name).exe
+	cp $< $@
+
+# build for local use, non-windows
+$(exec_base_name): $(release_name)-$(current_arch)/$(exec_base_name)
+	cp $< $@

README.md

@@ -1,81 +1,64 @@
-# Eduhub API validator
+# Apie 🙈 OpenAPI Service Validator
 
-A command-line tool to spider and validate [Open Education
-API](https://openonderwijsapi.nl/) endpoints to ensure compatibility
-with services in
-[SURFeduhub](https://www.surf.nl/surfeduhub-veilig-uitwisselen-van-onderwijsdata).
+A command-line tool to spider and validate API endpoints to ensure
+compatibility with OpenAPI v3 specs.
 
-This tool is intended for developers of OOAPI endpoints at educational
-institutions or their software suppliers.
+Apie takes an OpenAPI description of your service and crawls the
+endpoints, evaluating the interactions as it goes. It then generates a
+compact report containing all the validation issues found.
 
-## Downloading a release
+# For service developers
 
-This repository contains the source code & configuration of the
-validator. If you only need to run the builtin validations, download
-the latest build for your platform from [the Releases
-page](https://github.com/SURFnet/eduhub-validator/releases).
+Use Apie to get quick and readable feedback during development.
 
-The released builds contain a standalone binary `eduhub-validator`
-that has the configuration for multiple OOAPI profiles builtin.
+Run Apie from your automated tests to prevent regressions.
 
-## For OOAPI endpoint developers
+Apie helps you to validate that your service is behaving according to
+spec. Apie is a free, open source, standalone tool that talks to your
+service like any other HTTP client. If you have an OpenAPI v3
+specification for your API, you need minimal configuration to specify
+seed points and rules.
 
-The eduhub-validator binary contains a set of profiles which can be
-used to validate an OpenAPI endpoint for specific use cases.
+# For standards bodies
 
-Endpoints are not required to implement every path in the
-specification, 
+Use Apie to ensure adherence to your standards.
 
-Validating an endpoint works in two steps:
+When you're publishing specifications for others to implement, you
+want to provide all the automated support you can. With Apie, you can
+take your service description as a standard OpenAPI v3 document, add a
+simple rule set and quickly evaluate any implementation to ensure
+adherence!
 
-  - Spidering the endpoint and validating the responses. This will
-    create a large file with "observations"; a sequence of
-    request/response pairs and the associated validation issues.
-
-  - Aggregating the observations into a readable HTML report.
-
-## Spidering an endpoint directly
+# Usage
 
 ```sh
-eduhub-validator --base-url https://your-endpoint/
+apie --profile example-profiles/petstore.edn \
+     --base-url https://petstore3.swagger.io/api/v3
 ```
 
-This will exhaustively index your endpoint paths, validate against the
-default `rio` profile and write a report to `report.html` which can be
-opened using any web browser.
+This will spider the paths in the profile, validate against the
+included openapi specification and write a report to `report.html`
+which can be opened using any web browser. See the [petstore example
+report](https://surfnet.github.io/apie/example-report.html).
 
 The intermediate validation results are written to
 `observations.edn`. This file is in [EDN
 format](https://github.com/edn-format/edn) which is similar to JSON
 and can be read as text, but it will probably be very large.
 
-## Spidering via gateway
-
-To run the spider through the Eduhub gateway, you can use the
-`--basic-auth` and `--headers` options:
-
-```sh
-eduhub-validator \
-  --profile rio
-  --base-url https://gateway.test.surfeduhub.nl/ \
-  --basic-auth USERNAME:PASS \
-  --add-header 'x-route: endpoint=demo04.test.surfeduhub.nl' \
-  --add-header 'accept: application/json; version=5' \
-  --add-header 'x-envelope-response: false'
-```
+See our [configuration documentation](./docs/specification-authors.md)
+for more details.
 
-## Available Eduhub profiles
+## Downloading a release
 
-A few Eduhub profiles are available in the [profiles](./profiles)
-directory and are built into the binary releases:
+This repository contains the source code & example configuration of
+Apie. If you only need to run the your own validations, download the
+latest build for your platform from [the Releases
+page](https://github.com/SURFnet/apie/releases).
 
-  - `ooapi` -- the full OOAPI v5 specification
-  - `rio` -- the RIO profile of OOAPI v5.
-
-The RIO profile defines the subset of the OOAPI that RIO Mapper
-service requires.
+The released builds contain a standalone binary `apie`.
 
-# Extending the validator
+# Developing Apie
 
 ## Prerequisites for running/building from source
 
@@ -87,13 +70,30 @@ runtime, or the full [Clojure
 installation](https://clojure.org/guides/install_clojure) which
 requires Java and is slower to start.
 
-The `validator` script in the root of the repository will use Babashka
-if `bb` is on the PATH, and `clojure` otherwise.
+For running the validator without building, you can use the
+`dev/validate` or `dev/validate.bat` script.
+
+The `dev/validate` script will use Babashka if `bb` is on the PATH,
+and `clojure` otherwise.
+
+Alternatively, start a Clojure REPL and go from there.
 
-## For specification authors
+## Building Apie
+
+The Makefile can build a release for your current operating system:
+
+```
+make apie  # on linux / macos
+```
+
+or
+
+```
+make apie.exe  # for windows (untested)
+```
 
-Information about writing specification profiles can be found in
-[docs/specification-authors.md](./docs/specification-authors.md).
+We build releases for all supported platforms on Github; see
+`.github/workflows/build.yaml` for details.
 
 # Reporting vulnerabilities
 

bb.edn

@@ -1,3 +1,3 @@
-{:paths ["src" "assets" "profiles"]
+{:paths ["src" "assets"]
  :deps
  {this/project {:local/root "."}}}

deps.edn

@@ -1,4 +1,4 @@
-{:paths   ["src" "assets" "profiles"]
+{:paths   ["src" "assets"]
  :deps    {org.clojure/tools.cli          {:mvn/version "1.0.219"}
            ring/ring-codec                {:mvn/version "1.2.0"}
            org.babashka/http-client       {:mvn/version "0.4.15"}

dev/current_arch.clj

@@ -0,0 +1,17 @@
+(ns current-arch
+  (:require [clojure.string :as string]))
+
+(def systems
+  {"win"   "windows"
+   "mac"   "macos"
+   "linux" "linux"})
+
+(def system
+  (let [n (-> (System/getProperty "os.name" "unknown")
+              (string/lower-case))]
+    (some (fn [[sub os]]
+            (when (string/index-of n sub)
+              os))
+          systems)))
+
+(println (str system "-" (System/getProperty "os.arch" "unknown")))

validate → dev/validate

@@ -6,4 +6,4 @@ else
     RUNTIME="clojure -M"
 fi
 
-${RUNTIME} -m nl.jomco.eduhub-validator.main "$@"
+${RUNTIME} -m nl.jomco.apie.main "$@"

validate.bat → dev/validate.bat

@@ -6,4 +6,4 @@ if ERRORLEVEL 0 (
 ) else (
   set RUNTIME="clojure -M"
 )
-%RUNTIME% -m nl.jomco.eduhub-validator.main %*
+%RUNTIME% -m nl.jomco.apie.main %*