Reorder menu

.editorconfig

@@ -0,0 +1,5 @@
+root = true
+
+[*.md]
+indent_size = 2
+indent_style = space

api-documentation/2.3.complete-api-documentation.md → api-documentation/complete-api-documentation.md

@@ -2,16 +2,16 @@
 
 ## Story
 
-As a API consumer
-I want to be able to get an extensive description of the API's data structures and capabilities
-so that I can use API testing tools, make some client-side pre-computations or create a documentation out of it.
+> As a API consumer<br>
+> I want to be able to get an extensive description of the API's data structures and capabilities<br> 
+> so that I can use API testing tools, make some client-side pre-computations or create a documentation out of it.
 
 ## Details
 
 Hydra is an RDF vocabulary, thus it is enabled to provide extensive meta-data descriptions for both 
 payload embedded and entry-point level hypermedia controls. While it may be impossible to provide 
 as rich description as in case of the embedded description, still API documentation should be capable 
-to provide extensive details about API for various usages. These descriptions should cover:
+of providing extensive details about API for various usages. These descriptions should cover:
 - supported classes with:
   - name
   - description
@@ -134,4 +134,4 @@ It is currently impossible to describe expected or returned cardinality of the l
 gathered above. Both `hydra:returns` and `hydra:expects` are allowed to receive statements related 
 to multiple resources of same type. While for `PUT` operations server may use only statements related 
 to the resource identified by the call's URL, in case of `POST` where the resource will have no 
-explicit identifier server may end up with an 4XX or some other unexpected behavior.
+explicit identifier server may end up with an 4XX or some other unexpected behavior.

api-documentation/2.1.api-documentation-data-structures.md → api-documentation/data-structures.md

@@ -1,14 +1,16 @@
-# API documentation data structures
+# Data structures
 
 ## Story
 
-As an application user
-I want to be presented with some editor forms
-So I can fill it with my data.
+> As an application user<br>
+> I want to be presented with some editor forms<br>
+> So I can fill it with my data.
 
-As an API consumer
-I want to be able to fetch entry-point's supported classes
-So I can pre-generate views and forms.
+<!-- -->
+
+> As an API consumer<br>
+> I want to be able to fetch entry-point's supported classes<br>
+> So I can pre-generate views and forms.
 
 
 ## Usage
@@ -91,7 +93,7 @@ HTTP 200 OK
 }
 ```
 
-By composing both payload and context client can gain knowledge on how the data 
+By composing both payload and context client can gain knowledge on what the data 
 element structure looks like (i.e. properties, their names and data types).
 With this knowledge it is possible to i.e. generate generic HTML views for 
-editing or creating data items or to support dynamic IRI template composition.
+editing or creating data items, or to support dynamic IRI template composition.

api-documentation/1.entry-point.md → api-documentation/entry-point.md

@@ -2,9 +2,9 @@
 
 ## 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.
+> As an application user <br>
+> I want my application to consume an entry point for the Web API by providing a base URL<br>
+> So I can start managing my events.
 
 
 ## Usage
@@ -122,11 +122,11 @@ statement (in Turtle):
 [] a hydra:Operation .
 ```
 
-This is due to fact that Hydra Core Vocabulary provides an *rdfs:domain* for *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.
+This is due to fact that Hydra Core Vocabulary provides an *rdfs:domain* for *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 [security considerations](../1.1.security-considerations.md)  document.
+Please refer to the [security considerations](../security-considerations.md)  document.

api-documentation/2.2.api-documentation-user-document.md → api-documentation/generating-user-document.md

@@ -1,15 +1,17 @@
-# API documentation user document
+# Generating user document
 
 ## Story
 
-As an application user
-I want to be presented with some user readable API documentation
-So I can link it to my project's documentation for business and project
+> As an application user<br>
+>I want to be presented with some user readable API documentation<br>
+>So I can link it to my project's documentation for business and project
 unrelated people.
 
-As an API consumer
-I want to be able to fetch entry-point's API documentation
-So I can build an nice looking API documentation.
+<!-- -->
+
+> As an API consumer<br>
+> I want to be able to fetch entry-point's API documentation<br>
+> So I can build an nice looking API documentation.
 
 
 ## Usage
@@ -38,8 +40,8 @@ It is common to create project documentations, including end point details.
 By providing detailed description of the entry point API, it is possible to 
 create automated documentation generators.
 
-Communication would look like those described in [this](./1.entry-point.md), 
-[this](./2.api-documentation.md) and [this](./2.1.api-documentation-data-structures.md)
+Communication would look like those described in [this](./entry-point.md), 
+[this](./overview.md) and [this](./data-structures.md)
 documents.
 
 Resulting documentation should contain these details:

api-documentation/2.api-documentation.md → api-documentation/overview.md

@@ -1,10 +1,10 @@
-# API Documentation
+# API Documentation overview
 
 ## Story
 
-As a API consumer
-I want to be able to get an overview of the structure and capabilities of a Hydra API
-so that I can understand how to interact with the API and make those interactions more efficient.
+> As a API consumer <br>
+> I want to be able to get an overview of the structure and capabilities of a Hydra API<br>
+> so that I can understand how to interact with the API and make those interactions more efficient.
 
 
 ## Usage
@@ -94,7 +94,7 @@ The documentation should also contain some human readable details like:
 ### Entry-Point/API Documentation fetching precedence
 
 In the previous scenario, application fetched an entry-point data as its first action.
-It might be worth of considering the opposite - taking an API documentation if available.
+It might be worth to considering the opposite - taking an API documentation if available.
 
 Few possibilities here are available:
 - sending an _OPTIONS_ HTTP request to the base URL,
@@ -123,13 +123,13 @@ i.e. how can we obtain all instances or how we can create a new one.
 This may be an alternative to entry point, where an UI application could create it's main menu
 presented to the user with all possibilities, from which some may be denied later.
 In case of an entry-point and embedded hypermedia controls,
-only those that are allowed in the current state are expect .
-Currently, Hydra Core Vocabulary does not give a clear answer on how such a construct should be created and handler.
+only those that are allowed in the current state are expect.
+Currently Hydra Core Vocabulary does not give a clear answer on how such a construct should be created and handled.
 
 
 ### API documentation and hypermedia controls precedence
 
-It is unclear on how details obtain from API documentation and current hypermedia controls should be "merged".
+It is unclear on how details obtained from API documentation and current hypermedia controls should be "merged".
 There are few possibilities here:
 
 - hypermedia controls overrides API documentation
@@ -141,6 +141,6 @@ Hydra Core Vocabulary specification would introduce several weaknesses in all ca
 - if the control extends API documentation behavior, there is no mechanism that would force it to override it instead
 
 ### More specific situations:
-- [API documentation data structures](./2.1.api-documentation-data-structures.md)
-- [API documentation user document](./2.2.api-documentation-user-document.md)
-- [Complete API documentation](./2.3.complete-api-documentation.md)
+- [API documentation data structures](./data-structures.md)
+- [API documentation user document](./generating-user-document.md)
+- [Complete API documentation](./complete-api-documentation.md)

drafts/6.updating-event.md

@@ -83,7 +83,7 @@ The event should be now updated.
 
 ### What does the term "update" means?
 
-As mentioned in the [previous use case](/4.obtaining-single-event.md), the application is not aware
+As mentioned in the [previous use case](./4.obtaining-single-event.md), the application is not aware
 of the kind of data that will be provided by the server, thus a simple question arises:
 
 *What gets updated?*

summary.md

@@ -1,17 +1,18 @@
+* [Preamble](assumptions.md)
 * Examples
   * [Movies](movies/index.md)
     * [1 API entry point](movies/entry-point.md)
     * [2 The JSON-LD context](movies/context.md)
     * [3 The API documentation](movies/api-doc.md)
     * [4 Create a movie](movies/create-movie.md)
+* Anatomy of API Documentation
+  * [Overview](api-documentation/overview.md)
+  * [Entrypoint](api-documentation/entry-point.md)
+    * [Security considerations](security-considerations.md)
+  * [Data structures](api-documentation/data-structures.md)
+  * [Complete API Documentation](api-documentation/complete-api-documentation.md)
+  * [Generating user documentation](api-documentation/generating-user-document.md)
 * Drafts
-  * [Assumptions](assumptions.md)
-  * [1 Entrypoint](api-documentation/1.entry-point.md)
-    * [1.1 Security considerations](1.1.security-considerations.md)
-  * [2 API Documentation](api-documentation/2.api-documentation.md)
-    * [2.1 Data structures](api-documentation/2.1.api-documentation-data-structures.md)
-    * [2.2 User document](api-documentation/2.2.api-documentation-user-document.md)
-    * [2.3 Complete API Documentation](api-documentation/2.3.complete-api-documentation.md)
   * [3 Obtaining events](drafts/3.obtaining-events.md)
     * [3.1 Extensions considerations](drafts/3.1.extensions-considerations.md)
     * [3.2 Pagination](drafts/3.2.pagination.md)