tutorial: rest_api example

OwnYourData · Mar 8, 2022 · 2f97a3f · 2f97a3f
1 parent cd6e5ca
commit 2f97a3f
Show file tree

Hide file tree

Showing 5 changed files with 347 additions and 13 deletions.
diff --git a/cli/cmd.txt b/cli/cmd.txt
@@ -3,4 +3,5 @@ docker run --rm -v $(pwd):/data jplimce/bikeshed:3.2.0 bikeshed spec /data/index
 file:///Users/christoph/semcon/soya/docs/index.html
 
 # test docker image
-docker run -it --rm -w /usr/src/app/docker/test oydeu/soya-cli:latest /usr/src/app/docker/test/run.sh
+docker run -it --rm -w /usr/src/app/docker/pytest oydeu/soya-cli:alpha pytest
+#docker run -it --rm -w /usr/src/app/docker/test oydeu/soya-cli:latest /usr/src/app/docker/test/run.sh
diff --git a/tutorial/README.md b/tutorial/README.md
@@ -4,7 +4,7 @@
 
 This tutorial introduces the use of **S**emantic **O**verla**y** **A**rchitecture.
 
-**Content**    
+**<a id="top"></a>Content**    
 
 * [Describing Data Models in YAML](#1-describe-data-model-in-yaml)
 * [Publishing Structures](#2-publishing-structures)
@@ -15,20 +15,22 @@ This tutorial introduces the use of **S**emantic **O**verla**y** **A**rchitectur
 
 To execute commands in the steps below make sure to have the following tools installed:    
 * `soya`: download and installation instructions [available here](https://github.com/OwnYourData/soya/tree/main/cli)    
+    TL;DR: just run `npm i -g soya-cli@latest` or update with `npm update -g soya-cli`
 * `jq`: download and installation instructions [available here](https://stedolan.github.io/jq/download/)    
 * `jolt`: download and installation instructions [available here](https://github.com/bazaarvoice/jolt/)
 
 Alternatively, you can use a ready-to-use Docker image with all tools pre-installed:    
 [https://hub.docker.com/r/oydeu/soya-cli](https://hub.docker.com/r/oydeu/soya-cli) 
 
-Use the following command to start the image:    
-
-```console
-docker run -it --rm -v ~/.soya:/home/user oydeu/soya-cli
-```
-
-*Note:* since it makes sense to keep data beyond a Docker session, a directory is mounted in the container to persist files; create this local directory with the command `mkdir ~/.soya`
+> Use the following command to start the image:    
+> 
+> ```console
+> docker run -it --rm -v ~/.soya:/home/user oydeu/soya-cli
+> ```
+> 
+> *Note:* since it makes sense to keep data beyond a Docker session, a directory is mounted in the container to persist files; create this local directory with the command `mkdir ~/.soya`
 
+[back to top ↑](#top)
 
 ## 1. Describing Data Models in YAML
 
@@ -193,7 +195,7 @@ curl -s https://playground.data-container.net/employee | jq -r .yml | soya init
 
 #### Classes
 
-* `subClassOf`    
+* **`subClassOf`**    
 
 To inherit properties from another existing class you can use `subClassOf` within a base. In the following example we inherit `Person` from `Agent` (which in turn is inherited from the class with the same name in the [FOAF Ontology](https://en.wikipedia.org/wiki/FOAF_(ontology)) - also note referencing the foaf namespace in the `meta` section at the top:
 
@@ -216,7 +218,6 @@ content:
         did: string
 ```
 
-
 <details>
   <summary>Output</summary>
 
@@ -270,7 +271,182 @@ curl -s https://playground.data-container.net/foaf_person | jq -r .yml | soya in
 
 </details>
 
-* Indentation    
+* **Indentation**    
+
+`subClassOf` provides a powerful way to inherit properties from any parent class. With `subClasses` and indentation data model authors can implicitly define nested data structures as shown in the next example: `GET`, `POST`, `PUT`, and `DELETE` are subclasses of `Service` and inherit the `endpoint` property.
+
+```yaml
+# based on: https://rapidapi.com/blog/api-glossary/payload/
+meta:
+  name: RESTful
+  context: https://ns.ownyourdata.eu/ns/soya-context.json 
+
+content:
+  bases: 
+    - name: Service
+      attributes:
+        endpoint: String
+      subClasses:
+        - name: GET
+          attributes:
+            responsePayload: ResponsePayload
+        - name: POST
+          attributes:
+            requestPayload: RequestPayload
+            responsePayload: ResponsePayload
+        - name: PUT
+          attributes:
+            requestPayload: RequestPayload
+        - name: DELETE
+    - name: RequestPayload
+      attributes:
+        interfaceType: String
+        methodName: String
+        parameters: String
+    - name: ResponsePayload
+      attributes:
+        responseType: String
+      subClasses:
+        - name: ResponsePayloadFailed
+          attributes:
+            messages: String
+        - name: ResponsePayloadOK
+          attributes:
+            data: String
+```
+
+<details>
+  <summary>Output</summary>
+
+Use the following command to generate the output:    
+```bash
+curl -s https://playground.data-container.net/rest_api | jq -r .yml | soya init
+```
+
+```json-ld
+{
+  "@context": {
+    "@version": 1.1,
+    "@import": "https://ns.ownyourdata.eu/ns/soya-context.json",
+    "@base": "https://soya.data-container.net/RESTful/"
+  },
+  "@graph": [
+    {
+      "@id": "Service",
+      "@type": "owl:Class",
+      "subClassOf": "soya:Base"
+    },
+    {
+      "@id": "endpoint",
+      "@type": "owl:DatatypeProperty",
+      "domain": "Service",
+      "range": "xsd:string"
+    },
+    {
+      "@id": "GET",
+      "@type": "owl:Class",
+      "subClassOf": "Service"
+    },
+    {
+      "@id": "responsePayload",
+      "@type": "owl:DatatypeProperty",
+      "domain": "GET",
+      "range": "ResponsePayload"
+    },
+    {
+      "@id": "POST",
+      "@type": "owl:Class",
+      "subClassOf": "Service"
+    },
+    {
+      "@id": "requestPayload",
+      "@type": "owl:DatatypeProperty",
+      "domain": "POST",
+      "range": "RequestPayload"
+    },
+    {
+      "@id": "responsePayload",
+      "@type": "owl:DatatypeProperty",
+      "domain": "POST",
+      "range": "ResponsePayload"
+    },
+    {
+      "@id": "PUT",
+      "@type": "owl:Class",
+      "subClassOf": "Service"
+    },
+    {
+      "@id": "requestPayload",
+      "@type": "owl:DatatypeProperty",
+      "domain": "PUT",
+      "range": "RequestPayload"
+    },
+    {
+      "@id": "DELETE",
+      "@type": "owl:Class",
+      "subClassOf": "Service"
+    },
+    {
+      "@id": "RequestPayload",
+      "@type": "owl:Class",
+      "subClassOf": "soya:Base"
+    },
+    {
+      "@id": "interfaceType",
+      "@type": "owl:DatatypeProperty",
+      "domain": "RequestPayload",
+      "range": "xsd:string"
+    },
+    {
+      "@id": "methodName",
+      "@type": "owl:DatatypeProperty",
+      "domain": "RequestPayload",
+      "range": "xsd:string"
+    },
+    {
+      "@id": "parameters",
+      "@type": "owl:DatatypeProperty",
+      "domain": "RequestPayload",
+      "range": "xsd:string"
+    },
+    {
+      "@id": "ResponsePayload",
+      "@type": "owl:Class",
+      "subClassOf": "soya:Base"
+    },
+    {
+      "@id": "responseType",
+      "@type": "owl:DatatypeProperty",
+      "domain": "ResponsePayload",
+      "range": "xsd:string"
+    },
+    {
+      "@id": "ResponsePayloadFailed",
+      "@type": "owl:Class",
+      "subClassOf": "ResponsePayload"
+    },
+    {
+      "@id": "messages",
+      "@type": "owl:DatatypeProperty",
+      "domain": "ResponsePayloadFailed",
+      "range": "xsd:string"
+    },
+    {
+      "@id": "ResponsePayloadOK",
+      "@type": "owl:Class",
+      "subClassOf": "ResponsePayload"
+    },
+    {
+      "@id": "data",
+      "@type": "owl:DatatypeProperty",
+      "domain": "ResponsePayloadOK",
+      "range": "xsd:string"
+    }
+  ]
+}
+```
+
+</details>
 
 ### `overlays` Section
 

diff --git a/tutorial/examples/rest_api.jsonld b/tutorial/examples/rest_api.jsonld
@@ -0,0 +1,120 @@
+{
+  "@context": {
+    "@version": 1.1,
+    "@import": "https://ns.ownyourdata.eu/ns/soya-context.json",
+    "@base": "https://soya.data-container.net/RESTful/"
+  },
+  "@graph": [
+    {
+      "@id": "Service",
+      "@type": "owl:Class",
+      "subClassOf": "soya:Base"
+    },
+    {
+      "@id": "endpoint",
+      "@type": "owl:DatatypeProperty",
+      "domain": "Service",
+      "range": "xsd:string"
+    },
+    {
+      "@id": "GET",
+      "@type": "owl:Class",
+      "subClassOf": "Service"
+    },
+    {
+      "@id": "responsePayload",
+      "@type": "owl:DatatypeProperty",
+      "domain": "GET",
+      "range": "ResponsePayload"
+    },
+    {
+      "@id": "POST",
+      "@type": "owl:Class",
+      "subClassOf": "Service"
+    },
+    {
+      "@id": "requestPayload",
+      "@type": "owl:DatatypeProperty",
+      "domain": "POST",
+      "range": "RequestPayload"
+    },
+    {
+      "@id": "responsePayload",
+      "@type": "owl:DatatypeProperty",
+      "domain": "POST",
+      "range": "ResponsePayload"
+    },
+    {
+      "@id": "PUT",
+      "@type": "owl:Class",
+      "subClassOf": "Service"
+    },
+    {
+      "@id": "requestPayload",
+      "@type": "owl:DatatypeProperty",
+      "domain": "PUT",
+      "range": "RequestPayload"
+    },
+    {
+      "@id": "DELETE",
+      "@type": "owl:Class",
+      "subClassOf": "Service"
+    },
+    {
+      "@id": "RequestPayload",
+      "@type": "owl:Class",
+      "subClassOf": "soya:Base"
+    },
+    {
+      "@id": "interfaceType",
+      "@type": "owl:DatatypeProperty",
+      "domain": "RequestPayload",
+      "range": "xsd:string"
+    },
+    {
+      "@id": "methodName",
+      "@type": "owl:DatatypeProperty",
+      "domain": "RequestPayload",
+      "range": "xsd:string"
+    },
+    {
+      "@id": "parameters",
+      "@type": "owl:DatatypeProperty",
+      "domain": "RequestPayload",
+      "range": "xsd:string"
+    },
+    {
+      "@id": "ResponsePayload",
+      "@type": "owl:Class",
+      "subClassOf": "soya:Base"
+    },
+    {
+      "@id": "responseType",
+      "@type": "owl:DatatypeProperty",
+      "domain": "ResponsePayload",
+      "range": "xsd:string"
+    },
+    {
+      "@id": "ResponsePayloadFailed",
+      "@type": "owl:Class",
+      "subClassOf": "ResponsePayload"
+    },
+    {
+      "@id": "messages",
+      "@type": "owl:DatatypeProperty",
+      "domain": "ResponsePayloadFailed",
+      "range": "xsd:string"
+    },
+    {
+      "@id": "ResponsePayloadOK",
+      "@type": "owl:Class",
+      "subClassOf": "ResponsePayload"
+    },
+    {
+      "@id": "data",
+      "@type": "owl:DatatypeProperty",
+      "domain": "ResponsePayloadOK",
+      "range": "xsd:string"
+    }
+  ]
+}