Add architectural diagram to main repository

.travis.yml

@@ -0,0 +1,15 @@
+sudo: required
+dist: trusty
+before_install:
+  # Install LaTeX (for architecture diagram)
+  - sudo apt-get -qq update
+  - sudo apt-get install -y --no-install-recommends texlive-fonts-recommended texlive-latex-extra texlive-fonts-extra texlive-latex-recommended texlive-extra-utils latex-xcolor pgf
+script:
+  # Build architecture diagram
+  - cd drafts/diagram
+  - pdflatex -interaction=nonstopmode -halt-on-error hydra-architecture-diagram.tex
+  - latex    -interaction=nonstopmode -halt-on-error hydra-architecture-diagram.tex
+  - dvisvgm --no-fonts hydra-architecture-diagram.dvi hydra-architecture-diagram.svg
+after_success:
+  # Update gh-pages branch
+  - ./.travis_update_ghpages.sh

.travis_update_ghpages.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+# Only publish from the main repository's master branch
+REPO_NAME="HydraCG/Specifications"
+if [ "$TRAVIS_REPO_SLUG" != "$REPO_NAME" ] || [ "$TRAVIS_BRANCH" != "master" ] || [ "$TRAVIS_PULL_REQUEST" != "false" ]; then exit; fi
+echo -e "Generating gh-pages...\n"
+
+# Checkout the gh-pages branch
+REPO_PATH=$PWD
+pushd $HOME
+git clone --quiet --branch=gh-pages https://${GH_TOKEN}@github.com/$REPO_NAME gh-pages 2>&1 > /dev/null
+cd gh-pages
+
+# Don't update if already at the latest version
+if [[ `git log -1 --pretty=%B` == *$TRAVIS_COMMIT* ]]; then exit; fi
+
+# Update documents
+cp -r $REPO_PATH .
+
+# Commit and push latest version
+git add .
+git config user.name  "Travis"
+git config user.email "travis@travis-ci.org"
+git commit -m "Update to $TRAVIS_COMMIT."
+git push -fq origin gh-pages 2>&1 > /dev/null
+popd

drafts/diagram/.gitignore

@@ -0,0 +1,8 @@
+*.aux
+*.dvi
+*.fdb*
+*.fls
+*.log
+*.pdf
+*.svg
+*.synctex*

drafts/diagram/README.md

@@ -0,0 +1,166 @@
+# Hydra Architecture Diagram
+
+This repository contains work in progress for an architecture diagram of the [Hydra Core Vocabulary](http://www.hydra-cg.com/spec/latest/core/).
+
+## Overview
+
+![Latest diagram version](https://rubenverborgh.github.io/Hydra-Architecture-Diagram/hydra-architecture-diagram.svg)
+
+An arrow represents a dependency from a component on another.
+
+## Components
+
+### Web API
+**Web APIs consist of resources and collections.**
+
+#### Defined by Hydra
+- structural description of an API
+- metadata of an API
+
+### Resources
+**Resources are the atoms of (Hydra-enabled) REST Web APIs.**
+
+Resources can have one or more representations.
+If those representations are RDF-based formats (or support embedding RDF),
+then they describe the resource using elements from the Hydra Core Vocabulary.
+
+#### Defined by Hydra
+- how resources can incorporate Hydra descriptions and/or controls
+  - in particular, how descriptions and controls can be separated from data
+- describing representations
+  - properties that a resource representation will list
+
+#### Dependencies
+- on Errors, since resources can generate errors
+
+
+### Collections
+**Collections are sets of resources and associated behavior.**
+
+Collections can contain zero or more resources.
+Collections are resources themselves.
+
+#### Defined by Hydra
+- describing kinds of collections
+  - properties of their elements (type etc.)
+- describing representations
+  - (optional) properties of resources that a collection representation will list
+- describing operations on collections
+  - creation
+  - addition
+  - deletion
+
+#### Dependencies
+- on Resources, since a collection is a resource and contains resources
+
+
+### Errors
+**Errors describe what can go wrong during the interaction with a resource,
+and possible ways to address it.**
+
+#### Defined by Hydra
+- types of errors 
+- error metadata
+  - possible causes
+  - possible fixes
+- connecting errors to resources
+
+#### Dependencies
+none
+
+
+### Fields
+**Fields are places where clients can provide input.**
+
+#### Defined by Hydra
+- parameter description
+  - name
+- constraints
+  - range
+  - validation
+
+#### Dependencies
+none
+
+
+### URI Templates
+**URI Templates express how field values are combined into an URL.**
+
+#### Defined by Hydra
+- field serialization
+
+#### Dependencies
+- on Fields, since they are needed to fill out templates
+
+
+### Entity Bodies
+**Entity Bodies express how field values are combined into a request body (e.g., for `POST`/`PUT`/`PATCH`).**
+
+#### Defined by Hydra
+- entity structure
+  - JSON-LD and other RDF formats
+  - non-RDF formats
+- field serialization
+
+#### Dependencies
+- on Fields, since they are needed to fill out entity bodies
+
+
+### Paging
+**Pages partition collections into subsets such that
+each child resource appears on exactly one page.**
+
+Pages (only) change [application state](https://www.safaribooksonline.com/library/view/restful-web-services/9780596529260/ch04s05.html#id3189296).
+
+#### Defined by Hydra
+- page navigation
+  - next, previous
+  - first, last
+  - jump to specific page
+- page metadata
+  - current page number
+  - total number of pages
+  - number of items per page
+- ordering
+  - based on resource attributes
+- client-initiated paging
+  - determine ordering
+  - determine number of items per page
+
+#### Dependencies
+- on Collections, since they are being paged
+- on URI Templates, since some paging options require generating a page URI
+
+
+### Filtering
+**Filters select subsets of collections based on resource attributes.**
+
+Filters (only) change [application state](https://www.safaribooksonline.com/library/view/restful-web-services/9780596529260/ch04s05.html#id3189296).
+
+#### Defined by Hydra
+- availability of filters
+- conditions for applying a filter
+- the effect of a filter
+  - how a filter maps input values to a selection
+
+#### Dependencies
+- on Collections, since they are being filtered
+- on URI Templates, since some filters require generating a page URI
+- on Fields, since they relate the filter to its effect
+
+
+### Actions
+**Actions express manipulations of resources through representations.**
+
+Actions change [resource state](https://www.safaribooksonline.com/library/view/restful-web-services/9780596529260/ch04s05.html#id3189296).
+
+#### Defined by Hydra
+- availability of actions
+- conditions for executing an action
+- the effect of executing an action
+
+#### Dependencies
+- on Resources, since actions can be executed on them
+- on Collections, since actions can be executed on them
+- on Fields, since they relate the action to its effect
+- on Entity Bodies, since some actions require sending a request body

drafts/diagram/hydra-architecture-diagram.tex

@@ -0,0 +1,95 @@
+\documentclass{article}
+\usepackage[utf8]{inputenc}
+
+% Page setup
+\usepackage[a4paper,landscape,margin=2cm]{geometry}
+
+% Typography
+\usepackage[scaled]{helvet}
+\let\familydefault\sfdefault
+
+% Graphics
+\usepackage[usenames,svgnames]{xcolor}
+\usepackage{tikz}
+\usetikzlibrary{arrows,positioning}
+
+\begin{document}
+\pagestyle{empty}
+
+\tikzstyle{package} = [
+  rectangle, draw,
+  font = {\Large\bf}, align=left,
+  minimum height=13em, text width=54em, inner sep=1em,
+]
+\tikzstyle{subpackage} = [
+  rectangle, draw,
+  font = {\large\it}, align=left,
+  minimum height=8em, text width=11em, text height=-5em, inner sep=1em,
+]
+\tikzstyle{component} = [
+  rectangle, draw, fill=Khaki!50,
+  font = {\large\bf},
+  minimum width=10em, rounded corners, minimum height=4em,
+]
+\tikzstyle{arrow} = [
+  draw, -latex', line width=1pt,
+]
+
+\begin{tikzpicture}[
+    node distance = 2em, auto
+  ]
+
+  % Packages
+  \node[package, fill=CornflowerBlue!50]
+        (modeling) {API Modeling};
+  \node[package, fill=DarkOrange!50, above=of modeling, minimum height=21em]
+        (hypermedia) {Hypermedia\\Controls};
+  \node[subpackage, above left=of hypermedia.south east, anchor=south east, align=right]
+        (unsafe) {Unsafe};
+  \node[subpackage, left=of unsafe.south west, anchor=south east, text width=23em]
+        (safe) {Safe};
+  \node[subpackage, above=of unsafe.north east, anchor=south east, text width=38em]
+        (forms) {Forms};
+
+  % Nodes
+  \node[component, above left=of modeling.south, anchor=south, xshift=6.4em]
+        (resources) {Resources};
+  \node[component, above=of resources]
+        (collections) {Collections};
+  \node[component, left=of collections]
+        (api) {Web API};
+  \node[component, right=5.5em of resources]
+        (errors) {Errors};
+  \node[component, above right=of safe.south west, anchor=south west]
+        (paging) {Paging};
+  \node[component, right=of paging]
+        (filtering) {Filtering};
+  \node[component, above right=of forms.south west, anchor=south west]
+        (templates) {URI Templates};
+  \node[component,  above left=of forms.south east, anchor=south east]
+        (bodies) {Entity Bodies};
+  \node[component,  right=of templates]
+        (fields) {Fields};
+  \node[component, above right=of unsafe.south west, anchor=south west]
+        (actions) {Actions};
+
+  % Arrows
+  \path[arrow] (api)               -- (collections);
+  \path[arrow] (api.south east)    -- (resources.north west);
+  \path[arrow] (collections.south) -- (resources);
+  \path[arrow] (resources)         -- (errors);
+  \path[arrow] (paging.south)      -- (collections);
+  \path[arrow] (paging.north)      -- (templates.south);
+  \path[arrow] (filtering.south)   -- (collections);
+  \path[arrow] (filtering.north)   -- (templates.south);
+  \path[arrow] (filtering.north)   -- (fields);
+  \path[arrow] (actions.south)     -- (collections.east);
+  \path[arrow] (actions.south)     -- (resources.east);
+  \path[arrow] (actions.north)     -- (bodies);
+  \path[arrow] (actions.north)     -- (fields);
+  \path[arrow] (templates)         -- (fields);
+  \path[arrow] (bodies)            -- (fields);
+
+\end{tikzpicture}
+
+\end{document}