Use case documents for the entrypoint and a first draft of security c…

…onsiderations (#113)

* Let's consider first an entry-point use case of the Hydra client.
* Added entry-point use case.
* Feedback changes

drafts/use-cases/0.intro.md

@@ -0,0 +1,101 @@
+# Uses cases for Hydra Core Vocabulary client
+
+Here you can find some of the use cases to consider while developing a reference client implementation and improve Hydra Core Vocabulary specification.
+
+To create a context of the whole task, these use-cases are related to the [EventAPI](https://github.com/lanthaler/EventApiDemo) and a calendar-like UI web application.
+
+Each scenario is build using several sections:
+
+- Story - a short _As a... I want... so..._ story introducing a general requirement
+- Usage - a pseudo-code (JavaScript/TypeScript like) of the imaginary client
+- Details - detailed description
+- Considerations - some additional considerations on several aspects
+
+## Assumptions
+
+For simplification, some assumptions are made so the main topic of each of the use-cases are not distracted with side details.
+
+These would be:
+
+- client-server communication uses JSON-LD RDF serialization using HTTP headers:
+  Content-Type: application/ld+json for server responses
+  Accept: application/ld+json client requests
+- JSON-LD context is described later on in this document and is referenced in further example
+  payloads with this property:
+  ```javascript
+  {
+      "@context": "/api/context.jsonld"
+      // further example payload goes here
+  }
+  ```
+- to simplify, the host was dropped from all Urls. We can assume an example like http://example.com/.
+
+### JSON-LD context
+```javascript
+{
+    "@context": {
+        "hydra": "http://www.w3.org/ns/hydra/core#",
+        "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+        "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
+        "xsd": "http://www.w3.org/2001/XMLSchema#",
+        "owl": "http://www.w3.org/2002/07/owl#",
+        "schema": "http://schema.org/",
+        "title": {
+            "@id": "hydra:title",
+            "@type": "xsd:string"
+        },
+        "operations": {
+            "@id": "hydra:operation",
+            "@type": "hydra:Operation"
+        },
+        "method": {
+            "@id": "hydra:method",
+            "@type": "xsd:string"
+        },
+        "returns": {
+            "@id": "hydra:returns",
+            "@type": "hydra:Class"
+        },
+        "expects": {
+            "@id": "hydra:expects",
+            "@type": "hydra:Class"
+        },
+        "supportedClasses": {
+            "@id": "hydra:supportedClass",
+            "@type": "hydra:Class"
+        },
+        "supportedProperties": {
+            "@id": "hydra:supportedProperty",
+            "@type": "@id"
+        },
+        "property": {
+            "@id": "hydra:property",
+            "@type": "rdf:Property"
+        },
+        "members": {
+            "@id": "hydra:member",
+            "@type": "@id"
+        },
+        "totalItems": {
+            "@id": "hydra:totalItems",
+            "@type": "xsd:int"
+        },
+        "eventName": {
+            "@id": "schema:name",
+            "@type": "xsd:string"
+        },
+        "eventDescription": {
+            "@id": "schema:description",
+            "@type": "xsd:string"
+        },
+        "startDate": {
+            "@id": "schema:startDate",
+            "@type": "xsd:dateTime"
+        },
+        "endDate": {
+            "@id": "schema:endDate",
+            "@type": "xsd:dateTime"
+        }
+    }
+}
+```

drafts/use-cases/1.1.security-considerations.md

@@ -0,0 +1,40 @@
+### Security considerations
+
+#### JSON array root security issues
+Due to security issues with JSON arrays which can be exploited in some circumstances, 
+there may be a need to avoid pure arrays in favour of a JSON object.
+In the scenario above, server returned a single object, which won't cause issues.
+But it is possible to return multiple resources, resulting in an JSON array returned 
+(server may not use any JSON-LD context or it may be completely different from the one used by the client).
+There are several possibilities here. One of them would be to use a *@graph* notation, i.e.:
+
+```javascript
+{
+    "@graph": [
+        {
+            "@id": "/api",
+            "operations": [
+                {
+                    "@id": "/api/events",
+                    "title": "Events",
+                    "httpMethod": "GET",
+                    "returns": "hydra:Collection"
+                },
+                {
+                    "@id": "/api/events",
+                    "title": "Create new event",
+                    "httpMethod": "POST",
+                    "expects": "schema:Event"
+                }
+            ]
+        },
+        {
+            "rdfs:label": "Some other resource somehow related to the main one."
+        }
+    ]
+}
+```
+
+Using default graph seems reasonable, but implies some additional, possibly unwanted,
+logic of the graph itself.
+We could consider another approach or somehow standardize the graph name (if necessary).

drafts/use-cases/1.entry-point.md

@@ -0,0 +1,77 @@
+## Entry point
+
+### Story
+As an application user
+I want my application to consume an entry point for the Web API by providing a base URL
+So I can start managing my events.
+
+### Usage
+```javascript
+var client = new HydraClient();
+var entryPoint = client.get("http://example.com/").getEntryPoint();
+for (var operation of entryPoint.operations) {
+    // do something with the *operation*
+}
+```
+
+### Details
+It is simple to imagine a situation, when an application has a base URL provided, i.e.
+in a configuration or in the input field.
+Once provided, the application is expected to connect to the entry-point of the Web API and download initial
+details on what else can be done with that API from that very point.
+
+```
+GET /api
+
+HTTP 200 OK
+```
+```javascript
+{
+    "@id": "/api",
+    "operations": [
+        {
+            "@id": "/api/events",
+            "@type": "hydra:Operation",
+            "title": "Events",
+            "method": "GET",
+            "returns": "hydra:Collection"
+        },
+        {
+            "@id": "/api/events#new",
+            "@type": "hydra:Operation",
+            "title": "Create new event",
+            "method": "POST",
+            "expects": "schema:Event"
+        }
+    ]
+}
+```
+
+With this details, client application is aware of two possible operations that can be made from that point:
+
+- GET events
+- POST an event
+
+It is possible for a rich UI application with some fancy logic that would takes all
+GET operations returning *hydra:Collection* and displays them in a main menu.
+
+### Considerations
+
+#### RDFS entailment and OWL Reasoning capabilities
+Another thing is how far the client should be pushed into the reasoning process.
+In the example above, both operations have their type explicitely expressed with *"@type"* keyword.
+But in RDFS environment, it is possible to use only *hydra:method* and *hydra:expects* predicates, 
+which is fully legal as the entailment process would extend the resource */events* with additional
+statement (in Turtle):
+
+```
+</api/events> a hydra:Operation .
+```
+
+This is due to fact that Hydra Core Vocabulary provides an *rdfs:domain* for *hydra:method* .
+Unfortunately, many clients, especially browser based, won't use that process of entailment,
+thus an explicit statement should appear so the client can easily discover all the operations.
+
+#### Security considerations
+
+Please refer to the (this)[/1.1.security-considerations.md] for security considerations.