Rename to apie, remove eduhub-specific files

Adjust makefile to allow building standalone `apie` binary for the
local machine.

.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)
+current_arch=$(shell bb 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,12 @@ $(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)
+	echo $(current_arch)
+	cp $< $@

README.md

@@ -1,79 +1,61 @@
-# 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.
 
 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:
+See our [configuration documentation](./docs/specification-authors.md)
+for more details.
 
-```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'
-```
-
-## 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
 
@@ -90,10 +72,20 @@ 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 specification authors
+The Makefile can build a release for your current os:
+
+```
+make apie  # on linux / macos
+```
+
+or
+
+```
+make apie.exe  # on windows (untested)
+```
 
-Information about writing specification profiles can be found in
-[docs/specification-authors.md](./docs/specification-authors.md).
+We build for all supported platforms on Github; see
+`.github/workflows/build.yaml` for details.
 
 # Reporting vulnerabilities
 

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")))

docs/specification-authors.md

@@ -1,35 +1,16 @@
-# For Eduhub specification authors
+# For OpenAPI specification authors
 
-This document is intended for authors of the Open Education
-Specification and related profiles.
+This document is intended for authors of the OpenAPI specs and the
+related profile configuration.
 
 Before writing your own profiles and rules take a look at the
-available configuration files in the [profiles](../profiles) directory.
-
-# Profiles for different use cases
-
-The Open Education Specification has profiles for different consumers
-(use cases).
-
-Currently, we have a two profiles:
-
-- `ooapi` - the profile for a complete OOAPI implementation
-- `rio` - the minimum implementation needed for serving the RIO Consumer. 
-
-We describe a profile as a set of rules for indexing specific paths,
-plus a profile-specific OpenAPI specification (this is a subset of the
-generic OOAPI OpenAPI spec).
+available configuration files in the
+[example-profiles](../example-profiles) directory. More examples can
+be found in the [eduhub-validator
+profiles](https://github.com/SURFnet/eduhub-validator/tree/master/profiles)
 
 # OpenAPI Specifications
 
-OpenAPI specs subsets are created using
-[merge-yaml-tree](https://git.sr.ht/~jomco/merge-yaml-tree).
-
-This tool takes two directory trees with YAML files and generates a
-merged tree.  This can be used to create subsets of the [Open
-Education
-Specification](https://github.com/open-education-api/specification/tree/master/v5).
-
 The validator in this repository expects a JSON formatted single-file
 specification. To generate a JSON version of a YAML directory tree you
 can use the Redocly command line tool:
@@ -40,9 +21,6 @@ npx @redocly/openapi-cli bundle --ext=json spec.yaml --force >profile.json
 
 Where `spec.yaml` is the root YAML document.
 
-In this repository, the resulting JSON specifications are added to the
-[profiles](../profiles) directory.
-
 # Profile files
 
 An OpenAPI specification alone is not enough to index a service. The
@@ -188,3 +166,5 @@ the spidering and rules implementation.
 
 [https://git.sr.ht/~jomco/openapi-v3-validator](https://git.sr.ht/~jomco/openapi-v3-validator) -
 the OpenAPI validation implementation.
+
+[https://github.com/SURFnet/eduhub-validator/](https://github.com/SURFnet/eduhub-validator/) - Apie builds for OpenOnderwijsAPI endpoints.

example-profiles/petstore.edn

@@ -0,0 +1,20 @@
+{:openapi-spec "petstore.openapi.json"
+ :seeds
+ [{:method       "get"
+   :path         "/pet/findByStatus"
+   :query-params {"status" "pending"}}
+  {:method       "get"
+   :path         "/pet/findByStatus"
+   :query-params {"status" "available"}}
+  {:method       "get"
+   :path         "/pet/findByStatus"
+   :query-params {"status" "sold"}}
+  {:method "get"
+   :path   "/store/inventory"}]
+  :rules
+ [{:match     [[:request :method, "get"]
+               [:request :path "/pet/findByStatus"]
+               [:response :status 200]
+               [:response :body ?i "id" ?petId]]
+   :generates [{:method "get"
+                :path   "/pet/{ ?petId }"}]}]}