Path and query lowerCamelCase + example URLs (#159)

- Replaced "URI notation MUST use lowerCamelCase"  by "Path segments and query parameters SHOULD use lowerCamelCase"
- Added new rule "Naming of path parameters"
- Remove "/REST" path prefix from example URIs and use host https://api.socialsecurity.be

guide/src/main/asciidoc/api.adoc

@@ -27,12 +27,12 @@ Compare an API to the concept of https://www.informit.com/articles/article.aspx?
 ====
 *URI =* `https://`[green]#_host_#`/`[green]#_pathPrefix_#`/`[green]#_apiName_#`/v`[green]#_majorVersion_#`/`[green]#_resources_#
 
-[gray]#_example:_ \https://services.socialsecurity.be/REST/employerProfile/v1/profiles#
+[gray]#_example:_ \https://api.socialsecurity.be/REST/employerProfile/v1/profiles#
 
 `https://`:: Services are at least secured on transport level using a one-way TLS connection. The implicit port is 443.
 host:: Hostname is determined by the environment where the service is deployed
 pathPrefix:: Optional path prefix to discriminate between REST APIs and other resources on the same host. [gray]#(example: /REST)#
-apiName:: Name of the API that groups a functional consistent set of resources. The API name consists of one or multiple _path segments_ written in lowerCamelCase [gray]#(example: /referenceData/geography)#.
+apiName:: Name of the API that groups a functional consistent set of resources. The API name consists of one or multiple _path segments_ and SHOULD be written in lowerCamelCase [gray]#(example: /referenceData/geography)#.
 majorVersion:: Major version numbers are integers and start at 1. See <<API versioning>>.
 resources:: All path segments identifying the actual resources.
 ====

guide/src/main/asciidoc/api_specifications.adoc

@@ -121,6 +121,30 @@ Note that these are exceptions to the rule that API resource URLs shouldn't have
 Absent optional properties in a request are set by the API provider to their `default` value if one is specified in the OpenAPI specification.
 ====
 
+[rule, path-param]
+.Naming of path parameters
+====
+Path parameters SHOULD use *lowerCamelCase* notation.
+====
+
+|===
+|KO|OK
+
+a|
+```YAML
+paths:
+  /employers/{EmployerId}:
+    # ....
+```
+
+a|
+```YAML
+paths:
+  /employers/{employerId}:
+    # ....
+```
+|===
+
 [rule, oas-exampl]
 .Add examples in OpenAPI
 ====
@@ -240,6 +264,7 @@ The technical types referenced in this style guide are available in the https://
 Other types for business concepts commonly used by Belgian government institutions are available in other repositories.
 ====
 
+
 === JSON data types
 
 [rule, oas-types]
@@ -286,10 +311,8 @@ Pet:
   description: a pet in the pet store
   type: object
 ```
-
 |===
 
-
 `additionalProperties` can be used to put restrictions on other properties of a JSON object than those specified in the schema.
 
 [rule, addi-prop]

guide/src/main/asciidoc/index.adoc

@@ -15,7 +15,7 @@
 :imagesdir: images
 :stylesheet: my-theme.css
 :checkedbox: pass:normal[✔]
-:API: http://rest-reference.test.paas.socialsecurity.be/REST/demo/v1
+:API: https://api.socialsecurity.be/demo/v1
 
 https://www.belgif.be[<- Belgif Home]
 

guide/src/main/asciidoc/resources.adoc

@@ -6,28 +6,40 @@ A REST APIs exposes a set of _resources_. Resources model the _data and function
 
 === Resource URI
 
-Any resource is uniquely identified by a Uniform Resource Identifier or URI ({rfc3986}[RFC 3986​]).
+Any resource is uniquely identified by a Uniform Resource Identifier or URI ({rfc3986}[RFC 3986]).
 
 
-NOTE: URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]​ +
-​example:   \https://api.socialsecurity.be/employers/406798006​?lang=nl
+NOTE: URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ] +
+example:   \https://api.socialsecurity.be/demo/v1/employers/406798006?lang=nl
 
-URI must be intuitively structured.
+URIs must be intuitively structured.
+
+URI fragments point to a part of a resource's representation, and are never sent to the API, but handled locally by clients. They are thereby not specified in a REST API's specifications (OpenAPI).
 
 [rule, uri-notat]
 .URI notation
 ==========================
-The **URI notation MUST use _lowerCamelCase_ ** to enhance readability and to separate compound names.
+**Path segments and query parameters** within an API SHOULD use **lowerCamelCase** notation to enhance readability and to separate compound names.
+
 As lowerCamelCase is used for JSON property names as well, the casing is consistent throughout the API.
 Trailing slashes MUST NOT be used.
 ==========================
 
 .URI notation
 ====
-​[green]#GOOD:  \http://rest-reference.test.paas.socialsecurity.be/REST/demo/v1/socialSecretariats/331# +
- [red]#BAD:   \http://rest-reference.test.paas.socialsecurity.be/REST/demo/v1/Social_Secretariats/331# +
-​[red]#BAD:   \http://rest-reference.test.paas.socialsecurity.be/REST/demo/v1/social-secretariats/331# +
-​[red]#BAD:   \http://rest-reference.test.paas.socialsecurity.be/REST/demo/v1/socialSecretariats/331/#
+|===
+|GOOD|BAD
+
+|[green]#\https://api.socialsecurity.be/demo/v1/socialSecretariats/331# +
+| [red]#\https://api.socialsecurity.be/demo/v1/Social_Secretariats/331# +
+[red]#\https://api.socialsecurity.be/demo/v1/social-secretariats/331# +
+
+|[green]#\https://api.socialsecurity.be/demo/v1/socialSecretariats/331#
+|[red]#\https://api.socialsecurity.be/demo/v1/socialSecretariats/331/#
+
+|[green]#\https://api.socialsecurity.be/demo/v1/socialSecretariats?country=BE# +
+|[red]#\https://api.socialsecurity.be/demo/v1/Social_Secretariats?Country=BE#
+|===
 ====
 
 [rule, uri-extens]
@@ -42,8 +54,8 @@ Instead, look at how to express <<Media Types>> using HTTP headers.
 
 .URI extensions
 ====
-​[green]#GOOD: \http://rest-reference.test.paas.socialsecurity.be/REST/demo/v1/socialSecretariats​/331# +
-[red]#​BAD: \http://rest-reference.test.paas.socialsecurity.be/REST/demo/v1/socialSecretariats​/331.json#
+[green]#GOOD: \https://api.socialsecurity.be/demo/v1/socialSecretariats/331# +
+[red]#BAD: \https://api.socialsecurity.be/demo/v1/socialSecretariats/331.json#
 ====
 
 
@@ -59,14 +71,14 @@ The query component of a URI contains a set of parameters to be interpreted as a
 [[query-parameters]]
 .Query parameters
 ====
-​[green]#\http://rest-reference.test.paas.socialsecurity.be/REST/demo/v1/socialSecretariats​*?q=sdworx*# +
+[green]#\https://api.socialsecurity.be/demo/v1/socialSecretariats*?q=sdworx*# +
 Filter the resource collection using a search string.
 
-[green]#\http://rest-reference.test.paas.socialsecurity.be/REST/demo/v1/socialSecretariats/331​*?select=(name,address)*# +
+[green]#\https://api.socialsecurity.be/demo/v1/socialSecretariats/331*?select=(name,address)*# +
 Filter the resource properties to the ones specified in the `select` query parameter.
 
-[green]#\http://rest-reference.test.paas.socialsecurity.be/REST/demo/v1/socialSecretariats/331​*?lang=nl*# +
-Only return translatable properties in dutch.
+[green]#\https://api.socialsecurity.be/demo/v1/socialSecretariats/331*?lang=nl*# +
+Only return translatable properties in Dutch.
 ====
 
 [rule, qry-multi]