Add new HTTP REST API service

Update readme
bump version

Signed-off-by: Ashley Sommer <ashleysommer@gmail.com>

Author: ashleysommer

CHANGELOG.md

@@ -5,13 +5,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Python PEP 440 Versioning](https://www.python.org/dev/peps/pep-0440/).
 
 ## [Unreleased]
-### Nothing yet
 
-## [0.20.0] - 2022-09-08
+## [0.21.0] - 2023-03-31
+### In this release:
+
+### Added
+- New HTTP Server functionality
+  - run PySHACL as a persistent service, exposing an OpenAPI3.0-compatible REST interface
+- Detection of filename when downloading web attachments is added
+- Better detection of invalid integer values for sh:minLength and sh:maxLength string constraints.
 
-### Note, while this is a normal 0.x release, it also acts as the v1.0 release candidate.
-That means, if no glaring bugs or issues are found in this release after two weeks, this version will be re-released as 
-PySHACL v1.0.
+### Fixed
+- Opening a http link that has chunked encoding, or content-disposition attachment will now work correctly.
+
+
+## [0.20.0] - 2022-09-08
 
 ### In this release:
 
@@ -980,7 +988,8 @@ just leaves the files open. Now it is up to the command-line client to close the
 
 - Initial version, limited functionality
 
-[Unreleased]: https://github.com/RDFLib/pySHACL/compare/v0.20.0...HEAD
+[Unreleased]: https://github.com/RDFLib/pySHACL/compare/v0.21.0...HEAD
+[0.21.0]: https://github.com/RDFLib/pySHACL/compare/v0.20.0...v0.21.0
 [0.20.0]: https://github.com/RDFLib/pySHACL/compare/v0.19.1...v0.20.0
 [0.19.1]: https://github.com/RDFLib/pySHACL/compare/v0.19.0...v0.19.1
 [0.19.0]: https://github.com/RDFLib/pySHACL/compare/v0.18.1...v0.19.0

CITATION.cff

@@ -8,7 +8,7 @@ authors:
   given-names: "Nicholas"
   orcid: "http://orcid.org/0000-0002-8742-7730"
 title: "pySHACL"
-version: 0.20.0
+version: 0.21.0
 doi: 10.5281/zenodo.4750840
 license: Apache-2.0
 date-released: 2022-01-13

Dockerfile

@@ -9,13 +9,13 @@ WORKDIR /home/pyshacl
 RUN addgroup -g 1000 -S pyshacl &&\
     adduser --disabled-password --gecos "" --home "$(pwd)" --ingroup "pyshacl" --no-create-home --uid 1000 pyshacl
 WORKDIR /app
-LABEL org.opencontainers.image.version="0.19.1"
+LABEL org.opencontainers.image.version="0.21.0"
 COPY . .
 RUN chown -R pyshacl:pyshacl /home/pyshacl /app && chmod -R 775 /home/pyshacl /app
 USER pyshacl
 ENV PATH="/home/pyshacl/.local/bin:$PATH"
-RUN pip3 install poetry
-RUN poetry install --no-dev --extras "js"
+RUN pip3 install "poetry>=1.2.0,<2.0"
+RUN poetry install --no-dev --extras "js http"
 USER root
 RUN apk del build-dependencies
 USER pyshacl

README.md

@@ -17,7 +17,7 @@ The SHACL community has a discord server for discussion of topics around SHACL a
 
 [Use this invitation link: https://discord.gg/RTbGfJqdKB to join the server](https://discord.gg/RTbGfJqdKB)
 
-There is a \#pyshacl channel in which discussion around this python library can held, and you can ask for general pyshacl help too.
+There is a \#pyshacl channel for discussion of this python library, and you can ask for general SHACL help too.
 
 ## Installation
 Install with PIP (Using the Python3 pip installer `pip3`)
@@ -70,12 +70,13 @@ usage: pyshacl [-h] [-s [SHACL]] [-e [ONT]] [-i {none,rdfs,owlrl,both}] [-m]
                [-ef {auto,turtle,xml,json-ld,nt,n3}] [-V] [-o [OUTPUT]]
                DataGraph
 
-PySHACL 0.20.0 command line tool.
+PySHACL 0.21.0 command line tool.
 
 positional arguments:
   DataGraph             The file containing the Target Data Graph.
 
 optional arguments:
+  --server              Ignore all the rest of the options, start the HTTP Server.
   -h, --help            show this help message and exit
   -s [SHACL], --shacl [SHACL]
                         A file containing the SHACL Shapes Graph.
@@ -155,7 +156,7 @@ Some other optional keyword variables available on the `validate` function:
 * `data_graph_format`: Override the format detection for the given data graph source file.
 * `shacl_graph_format`: Override the format detection for the given shacl graph source file.
 * `ont_graph_format`: Override the format detection for the given extra ontology graph source file.
-* `iterate_rules`: Interate SHACL Rules until steady state is found (only works with advanced mode).
+* `iterate_rules`: Iterate SHACL Rules until steady state is found (only works with advanced mode).
 * `do_owl_imports`: Enable the feature to allow the import of subgraphs using `owl:imports` for the shapes graph and the ontology graph. Note, you explicitly cannot use this on the target data graph.
 * `serialize_report_graph`: Convert the report results_graph into a serialised representation (for example, 'turtle')
 * `check_dash_result`: Check the validation result against the given expected DASH test suite result.
@@ -176,6 +177,42 @@ You can get an equivalent of the Command Line Tool using the Python3 executable
 $ python3 -m pyshacl
 ```
 
+## Integrated OpenAPI3.0-compatible HTTP REST Service
+
+PySHACL now has a built-in validation service, exposed via an OpenAPI3.0-compatible REST API.
+
+Due to the additional dependencies required to run, this feature is an optional extra.
+
+You must first install PySHACL with the `http` extra option enabled:
+
+```bash
+$ pip3 install -U pyshacl[http]
+```
+
+When that is installed, you can start the service using the by executing the CLI entrypoint:
+
+```bash
+$ pyshacl --server
+# or
+$ pyshacl_server
+# or
+$ python3 -m pyshacl server
+```
+
+By default, this will run the service on localhost address `127.0.0.1` on port `8099`.
+
+To view the SwaggerUI documentation for the service, navigate to `http://127.0.0.1:8099/docs/swagger` and for the ReDoc version, go to `http://127.0.0.1:8099/docs/redoc`.
+
+To view the OpenAPI3 schema see `http://127.0.0.1:8099/docs/openapi.json`
+
+### Configuring the HTTP REST Service
+
+- You can force PySHACL CLI to start up in HTTP Server mode by passing environment variable `PYSHACL_SERVER=TRUE`. This is useful in a containerised service, where you will _only_ be running PySHACL in this mode.
+- `PYSHACL_SERVER_LISTEN=1.2.3.4` listen on a different IP Address or hostname
+- `PYSHACL_SERVER_PORT=8080` listen on given different TCP PORT
+- `PYSHACL_SERVER_HOSTNAME=example.org` when you are hosting the server behind a reverse-proxy or in a containerised environment, use this so PySHACL server knows what your externally facing hostname is
+
+
 
 ## Errors
 Under certain circumstances pySHACL can produce a `Validation Failure`. This is a formal error defined by the SHACL specification and is required to be produced as a result of specific conditions within the SHACL graph.