Merge branch 'master' of https://github.com/HydraCG/Specifications in…

…to issue/99_Add_support_for_describing_headers

.github/CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Hydra W3C Community Group
+
+This repository is being used for work in the Hydra W3C Community Group, governed by the
+[W3C Community License Agreement (CLA)](http://www.w3.org/community/about/agreements/cla/).
+To contribute, you must [join the Community Group](http://www.hydra-cg.com/#community).
+
+## How to contribute
+
+To advance Hydra, it is imperative that the community engages with us in discussing new and existing features. The only
+way to hope for an end result useful for as many people as possible is for the actual interested parties to collaborate
+throughout the process of building the Hydra's specification. This is the essence of an Open (Source) community.
+
+This document gathers some guidelines which should help make this collaboration as smooth as possible.
+These are not strict rules.
+
+### Getting in touch
+
+The best way to start contributing is to first spark some interest. This can be done by creating a GitHub issue
+(more on that below) but a quicker alternative is to reach out to the community through one of our channels mentioned below.
+
+#### Mailing list
+
+The more traditional, and traceable method is to sign up and contact us via the [mailing list][ml]. All messages
+are stored in an archive and can be used as reference in the future.
+
+[ml]: https://lists.w3.org/Archives/Public/public-hydra/
+
+#### Slack
+
+As means of instant communication we're monitoring a `#hydra` channel on the HTTP APIs Slack. To register, please
+go to http://slack.httpapis.com.
+
+#### Twitter
+
+You can also Tweet to [`@HydraCg`](https://twitter.com/hydracg)
+
+### GitHub issues
+
+Finally, GitHub is the final place to work on the specification in focused manner. Whenever you create an issue, please 
+try to follow some simple rules:
+
+* Be complete. Always share all the necessary information for others to understand the issue.
+* Be concise. Lengthy comments can easily sidetrack the main focus.
+* Be focused. Try to keep the discussion focused on a single subject. If there are additional plot twists, do consider
+creating another issue.
+* Be proactive. Do not hesitate to share ideas which address the raised issue.
+
+### Submitting pull requests
+
+Unless it's a trivial change, we encourage the following workflow when submitting pull requests to the specification:
+
+1. Make sure there is an issue reported. If not, **report it first**.
+1. Create another PR to the [cookbook repository](https://github.com/HydraCG/gitbook).
+   * in the PR show example snippets of relevant request/response payloads.
+   * if possible, provide some discussion which will be the basis for documentation pages.
+   * you may even want to show code snippets (pseudo-code is just fine) demonstrating the new or improved feature.
+2. The cookbook PR will be used to brainstorm the solution to the problem.
+3. Once a satisfactory solution is found, please proceed with creating a pull request to the specification repository.
+
+If you are not the sole contributor to a contribution (pull request), please identify all
+contributors in the pull request's body or in subsequent comments.
+
+To add a contributor (other than yourself, that's automatic), mark them one per line as follows:
+
+```
++@github_username
+```
+
+If you added a contributor by mistake, you can remove them in a comment with:
+
+```
+-@github_username
+```
+
+If you are making a pull request on behalf of someone else but you had no part in designing the
+feature, you can remove yourself with the above syntax.

.github/ISSUE_TEMPLATE/design-question.md

@@ -0,0 +1,13 @@
+---
+name: Design question
+about: Ask about API design with Hydra
+labels: design
+---
+
+## Describe your API requirement
+
+Details about the resources and their interaction in simple terms.
+
+## Solution(s)
+
+Enumeration of possible API designs choices which you consider.

.github/ISSUE_TEMPLATE/missing_feature.md

@@ -0,0 +1,20 @@
+---
+name: Missing feature
+about: Help us expand the Hydra vocabulary
+---
+
+## Describe the requirement
+
+A clear and concise description of what is missing from Hydra.
+
+## Hydra-agnostic example
+
+Without Hydra or JSON-LD in mind, please provide an example of client/server resource representations which are exchanged but cannot be properly modeled with Hydra.
+
+## Proposed solutions
+
+A description, or snippet, showing what extensions are necessary to describe the above using Hydra terms.
+
+## Alternative solutions
+
+If possible, please link or present how similar features are implemented with other API description technologies

.github/ISSUE_TEMPLATE/other.md

@@ -0,0 +1,8 @@
+---
+name: Other issue
+about: Use this for everything else
+---
+
+## Description
+
+Any relevant information related to the issue which can help resolving it.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,24 @@
+<!--
+  Before proceeding, please read the Pull Request section in CONTRIBUTING.md (linked on the right)
+-->
+
+## Summary
+
+<!--
+  Short introduction to the proposed changes
+-->
+
+## More details
+
+<!--
+  More verbose explanation of how this PR addresses reported issue(s).
+  
+  Eg. "Fixes #987 by adding a new `X` class to the vocabulary. It will allow to do Y"
+-->
+
+## Related cookbook PR 
+
+<!-- 
+  If the changes introduce new terms or propose a novel use of the existing, please consider linking
+  to the cookbook repo like HydraCG/cookbook#1234
+-->

spec/latest/core/core.jsonld

@@ -60,6 +60,10 @@
     "mapping": "hydra:mapping",
     "IriTemplateMapping": "hydra:IriTemplateMapping",
     "variable": "hydra:variable",
+    "offset": { "@id": "hydra:offset", "@type": "xsd:nonNegativeInteger" },
+    "limit": { "@id": "hydra:limit", "@type": "xsd:nonNegativeInteger" },
+    "pageIndex": { "@id": "hydra:pageIndex", "@type": "xsd:nonNegativeInteger" },
+    "pageReference": { "@id": "hydra:pageReference" },
     "returnsHeader": { "@id": "hydra:returnsHeader", "@type": "xsd:string" },
     "expectsHeader": { "@id": "hydra:expectsHeader", "@type": "xsd:string" },
     "defines": { "@reverse": "rdfs:isDefinedBy" },
@@ -535,6 +539,38 @@
       "range": "xsd:string",
       "vs:term_status": "testing"
     },
+    {
+      "@id": "hydra:offset",
+      "@type": "rdf:Property",
+      "label": "skip",
+      "comment": "Instructs to skip N elements of the set.",
+      "range": "xsd:nonNegativeInteger",
+      "vs:term_status": "testing"
+    },
+    {
+      "@id": "hydra:limit",
+      "@type": "rdf:Property",
+      "label": "take",
+      "comment": "Instructs to limit set only to N elements.",
+      "range": "xsd:nonNegativeInteger",
+      "vs:term_status": "testing"
+    },
+    {
+      "@id": "hydra:pageIndex",
+      "@type": "rdf:Property",
+      "subPropertyOf": "hydra:pageReference",
+      "label": "page index",
+      "comment": "Instructs to provide a specific page of the collection at a given index.",
+      "range": "xsd:nonNegativeInteger",
+      "vs:term_status": "testing"
+    },
+    {
+      "@id": "hydra:pageReference",
+      "@type": "rdf:Property",
+      "label": "page reference",
+      "comment": "Instructs to provide a specific page reference of the collection.",
+      "vs:term_status": "testing"
+    },
     {
       "@id": "hydra:returnsHeader",
       "@type": "rdf:Property",

spec/latest/core/index.html

@@ -1028,6 +1028,26 @@ <h3>Description of HTTP Status Codes and Errors</h3>
       -->
     </pre>
   </section>
+
+  <section>
+    <h3>Client initiated pagination</h3>
+
+    <p>There are situations when a client would like to provide a specific
+      collection limitations, i.e. by providing query-language like member
+      offset and limit or some specific page index and number of members
+      per page. This is doable with <i>offset</i>/<i>limit</i> or
+      <i>pageIndex</i>/<i>limit</i> predicates.</p>
+
+    <p>With those, it is possible to bind a template variables mapped
+      with externally obtained values (i.e. user interaction) the same way
+      as with other mappings.</p>
+
+    <p>While the predicates enlisted above accepts non-negative integer
+      numbers, there is also a possibility of providing a custom page
+      reference expressed via <i>pageReference</i> predicate. It is possible
+      to provide a custom page identifier (i.e. a GUID or a letter)
+      instead of a number.</p>
+  </section>
 </section>
 
 <!-- <section>