Merged building-a-template into creating-templates

docs/tutorials/creating-templates.md

@@ -1,6 +1,41 @@
-# Template requirements
+# Creating templates
 
-## PoC (proof of concept) requirements
+## The importance of templates
+Templates...
+- ... make it easier to implement new microservices
+- ... help you get started with the technology you know and love, or help you understand the structure of a service written in a technology/language you barely know
+- ... should be predictable. The naming and structure of templates
+should therefore match certain standards
+- ... make it easy to follow the constraints semantic.works places on services, and should therefore contain a basic set of features which ensures users can easily develop applications in them
+
+
+Templates are our way to familiarize users with semantic.works and to ensure users follow the best practices where possibl
+
+## The steps of developing a template
+A template should make sure that the semantic.works ecosystem keeps
+running. The construction of a template happens in a set of stages.
+
+Building a template without knowing the domain is near impossible.
+
+### Step 1: Basic service
+First one should implement a basic service in the base technology, to get a feeling of which technologies are suited for the template
+
+To begin, select the technology you would like to support. Look around for web frameworks which match the ideology of microservices. Search for the 'Ruby Sinatra' competitor for your language.
+
+Your next challenge is to implement a simple microservice for this
+purpose. As an example, you can write a service that returns the amount of Tasks in the store, and which allows you to set a Task as done. The service itself is not of importance, you'll learn lessons about the framework when you implement the microservice.
+
+Don't forget to run your microservice in a toy semantic.works project.
+That way you'll know that it actually works.
+[mu-project](https://github.com/mu-semtech/mu-project)
+offers a good starting point.
+
+### Step 2: PoC (Proof of Concept)
+Next up is the construction of a PoC (Proof of Concept).
+
+Once your service works, you can start abstracting it. Much of the code you've built would be used again when you implement another service in the same language. Go over the list of the PoC, ensure you've implemented each feature, and put this in a separate project. This project will become the template to use for the Tasks service. If all goes well, you'll end with a PoC template service, and a much shorter Tasks service.
+
+#### PoC requirements
 -   Respond to HTTP requests
     -   Parse JSON & JSONAPI payloads
     -   Support implementation of GET PUT PATCH POST DELETE
@@ -19,9 +54,20 @@
     -   Load user-code from `/app`
     -   Download & install dependencies on startup
 
-## Full template requirements
 
--   [**All requirements for the PoC**](#poc-proof-of-concept-requirements)
+### Step 3: Full template
+Then comes the standardisation, which requires some extra features to ensure the template can be used in practice.
+
+This includes going over the [list of features needed for the full template](#full-requirements).
+Go over the list of features and try to implement them in a clean
+fashion. More complex, and realistic microservices, like those
+automatically creating Tasks for all starred books you haven't read yet now become possible. This is the space where your microservice should be in.
+
+Document the use of the microservice, and get us to publish it on our GitHub space.
+
+#### Full requirements
+
+-   [**All requirements for the PoC**](#poc-requirements)
 
 -   Configuration
     -   Access environment variables [[2]](#notes)
@@ -51,7 +97,103 @@
         -   Enable debugging symbols (if possible)
         -   Enable error output (if configurable)
 
-## Helper functions
+
+## Extra considerations
+### Levels of abstraction
+
+Most developers like to abstract things. Make sure that nothing is
+repeated. Many of us like to get started quickly. These two ideas often don't go hand-in-hand. We dismiss non-generic abstractions and require consistent naming.
+
+Getting started should be trivial and has the highest priority. It
+should be intuitive to start using a new template. It should be easy to read code that was written in a template, even if it isn't yours.
+
+The following is a description of various topics on which consistency should be held. The description should be adapted to the use of your language. Ie: if you'd call sparql_query in Ruby, sparqlQuery in Java and sparql-query in Common Lisp.
+
+#### Defining HTTP endpoints
+
+Users will define HTTP endpoints to which their service will respond.
+Separate methods should be defined for separate types of call. The
+method should simply contain the name of HTTP verb, and the URL to which we respond. The system should allow the user to destructure the input and access the destructured contents. Calls may be defined in a block, but if that is the case, then the block should be repeatable.
+
+**Essentials:**
+-   Use simple name of HTTP verb
+-   Allow straight-forward destructuring of URL
+-   Support finding query parameters
+
+Example in Common Lisp:
+
+```lisp
+(defcall :get (“say” “hello” “to” name)
+  ;; responds to GET /say/hello/to/Aad?title=Sir
+  ;; name is bound to Aad
+  ;; (get-parameter “title”) yields “Sir”
+)
+
+```
+
+Example in Ruby:
+```ruby
+get “say/hello/to/:name” do |name|
+  # responds to GET /say/hello/to/Erika?title=Madam
+  # name is bound to erika
+  # params[:title] yields “Madam”
+end
+
+```
+
+Another example in Ruby:
+```ruby
+define_calls do |server|
+  server.get “say/hello/to/:name” do |name|
+    # responds to GET /say/hello/to/Erika?title=Madam
+    # name is bound to erika
+    # params[:title] yields “Madam”
+  end
+end                                     
+```
+
+#### Executing SPARQL queries
+
+We should mitigate SPARQL-injection whilst still ensuring the SPARQL
+queries are easy to recognise. Allow for injecting variables in a
+SPARQL-query string. Support escaping as separate methods. Query results
+should be parsed automatically so the user can easily process them.
+
+A SPARQL endpoint often differs in query and update endpoints. Hence we
+advise to use those two names for executing the queries.
+
+For languages which don't allow injecting variables into strings, magic
+is allowed. Keep it to an absolute minimum and try to mimic what is
+commonly found in other languages. It should be something which you can
+explain in a single sentence.
+
+Common Lisp example:
+```lisp
+(sparql-query “SELECT ?s ?p ?o WHERE
+  GRAPH <http://mu.semte.ch/application> {
+    ?s a foaf:Agent;
+       foaf:name ~A;
+       ?p ?o.
+  }”, (sparql-escape-string “Felix”))
+
+(sparql-update “INSERT DATA
+  GRAPH <http://mu.semte.ch/application> {
+    ext:Aad a foaf:Agent.
+  }”)                                                  
+```
+J
+
+Ruby example:
+```ruby 
+query “SELECT ?s ?p ?o WHERE
+  GRAPH <http://mu.semte.ch/application> {
+    ?s a foaf:Agent;
+       foaf:name #{username.sparql_escape};
+       ?p ?o.
+  }”
+```
+
+### Helper functions
 Ideally, your template should expose some helper functions, including
 but not limited to the following. Extra parameters can be added as 
 needed or wanted.
@@ -68,7 +210,7 @@ needed or wanted.
 
 *Note: camelcase is used in this documentation. However, when writing the helpers in the language of your choice, use the notation that is in line with the language in question.*
 
-### sparql_escape
+#### sparql_escape
 The following helper functions all have the same description/funcionality, but for different types. As such, the description column is omitted.
 
 **Description:** Converts the given object to a SPARQL-safe RDF object string with the right RDF-datatype.
@@ -85,7 +227,7 @@ This functions should be used especially when inserting user-input to avoid SPAR
 | sparql_escape_datetime | value: `datetime` |
 | sparql_escape_bool     | value: `bool`     |
 
-### Passing headers
+#### Passing headers
 The following headers should be passed when making queries:
 
 | Header name            | Type     | Description             |
@@ -96,6 +238,9 @@ The following headers should be passed when making queries:
 | MU-AUTH-USED-GROUPS    |          |                         |
 
 
+
+
+
 ## Notes
 
 1.  This constraint should be dropped in the distant future, but it is