update

content/api/foundations.md

@@ -4,7 +4,7 @@ The Foundations section outlines the design principles upon which the rest of th
 
 ## Provide Request-Ids for Introspection
 
-Include a `Request-Id` header in each API response, populated with a UUID value. By logging these values on the client, server and any backing services, it provides a mechanism to trace, diagnose and debug requests.
+Include a `Request-Id` header in each API response, populated with a uuid value. By logging these values on the client, server and any backing services, it provides a mechanism to trace, diagnose and debug requests.
 
 ## Divide Large Responses Across Requests with Ranges
 
@@ -37,11 +37,11 @@ allows for greater focus on larger and harder problems.
 
 Requests and responses will be made to address a particular resource or
 collection. Use the path to indicate identity, the body to transfer the
-contents and headers to communicate metadata. Query params may be used as a
+contents and headers to communicate metadata. Query parameters may be used as a
 means to pass header information also in edge cases, but headers are preferred
 as they are more flexible and can convey more diverse information.
 
-## Support ETags for Caching
+## Support `ETags` for Caching
 
 Include an `ETag` header in all responses, identifying the specific
 version of the returned resource. This allows users to cache resources

content/api/general-guidelines.md

@@ -20,7 +20,7 @@ By defining APIs outside the code, we want to facilitate early review feedback a
 Moreover, API definitions with standardized specification format also facilitate...
 
 - single source of truth for the API specification; it is a crucial part of a contract between service provider and client users
-- infrastructure tooling for API discovery, API GUIs, API documents, automated quality checks
+- infrastructure tooling for API discovery, API GUI, API documents, automated quality checks
 
 It is important to learn, that API First is not in conflict with the agile development principles that we love. Service applications should evolve incrementally — and so its APIs. Of course, API specification will and should evolve iteratively in different cycles, each starting with draft status and early team and peer review feedback.
 

content/api/how-to-model-workflows-in-rest-apis.md

@@ -6,7 +6,7 @@ There are three options:
 
 1. Use an Attribute for the Workflow’s State
 1. Use Hyperlinks for Workflow Transitions
-1. Use a Subresource for Workflow Transitions
+1. Use a `Subresource` for Workflow Transitions
 
 ## So which one should I pick?
 
@@ -18,7 +18,7 @@ As always, it depends on the context, but here are some quick guidelines:
 | --- | --- |
 | State Attribute | When there are no restrictions on the transitions. You can go from any state to any state at any time. The states are basically nothing more than a list of values. |
 | Transition Links | There are limits to which states you can go to depending on the current state. |
-| Transition Subresource | The workflow is configurable by users, so states and transitions among them are not fixed, but can be changed at runtime. |
+| Transition `Subresource` | The workflow is configurable by users, so states and transitions among them are not fixed, but can be changed at runtime. |
 
 ## Reference
 

content/api/http.md

@@ -105,7 +105,7 @@ OPTIONS are used to inspect the available operations (HTTP methods) of a given e
 
 Note: OPTIONS is rarely implemented, though it could be used to self-describe the full functionality of a resource.
 
-## Must: Fulfill Safeness and Idempotency Properties
+## Must: Fulfill Safeness and Idempotent Properties
 
 An operation can be:
 

content/api/json-guidelines.md

@@ -6,10 +6,10 @@ cases to allow JSON data to have an idiomatic form across teams and services.
 
 ## Must: Use Consistent Property Names
 
-## Must: Property names must be snake_case (and never camelCase)
+## Must: Property names must be snake case (and never `camelCase`)
 
-No established industry standard exists, but many popular Internet companies prefer snake_case: e.g. GitHub, Stack Exchange,
-Twitter. Others, like Google and Amazon, use both - but not only camelCase. It’s essential to establish a consistent look and
+No established industry standard exists, but many popular Internet companies prefer snake case: e.g. GitHub, Stack Exchange,
+Twitter. Others, like Google and Amazon, use both - but not only `camelCase`. It’s essential to establish a consistent look and
 feel such that JSON looks as if it came from the same hand.
 
 ## Must: Property names must be an ASCII subset
@@ -19,12 +19,12 @@ and subsequent characters can be a letter, an underscore, a dollar sign, or a nu
 
 ## Must: Use Consistent Property Values
 
-## Must: Boolean property values must not be null
+## Must: boolean property values must not be null
 
 Schema based JSON properties that are by design booleans must not be presented as nulls. A boolean is essentially a closed
 enumeration of two values, true and false. If the content has a meaningful null value, strongly prefer to replace the boolean
-with enumeration of named values or statuses - for example accepted_terms_and_conditions with true or false can be replaced
-with terms_and_conditions with values yes, no and unknown.
+with enumeration of named values or statuses - for example `accepted_terms_and_conditions` with true or false can be replaced
+with `terms_and_conditions` with values yes, no and unknown.
 
 ## Must: Date property values should conform to RFC 3399
 
@@ -68,7 +68,7 @@ To indicate they contain multiple values prefer to pluralize array names. This i
 
 ## Should: Empty array values should not be null
 
-Empty array values can unambiguously be represented as the the empty list, [].
+Empty array values can unambiguously be represented as the empty list: `[]`
 
 ## Should: Enumerations should be represented as Strings
 

content/api/naming.md

@@ -13,7 +13,7 @@ Example:
 This applies to concrete path segments and not the names of path parameters. For example `{purchase_order_id}` would be ok
 as a path parameter.
 
-## MUST: Use snake_case (never camelCase) for Query Parameters
+## MUST: Use `snake_case` (never `camelCase`) for Query Parameters
 
 Examples:
 
@@ -36,17 +36,17 @@ The trailing slash must not have specific semantics. Resource paths must deliver
 
 If you provide query support for sorting, pagination, filtering functions or other actions, use the following standardized naming conventions:
 
-- `q` — default query parameter (e.g. used by browser tab completion); should have an entity specific alias, like sku
+- `q` — default query parameter (e.g. used by browser tab completion); should have an entity specific alias, like `sku`
 - `limit` — to restrict the number of entries. See Pagination section below. Hint: You can use size as an alternate query string.
 - `cursor` — key-based page start. See Pagination section below.
 - `offset` — numeric offset page start. See Pagination section below. Hint: In combination with limit, you can use page as an alternative to offset.
 - `sort` — comma-separated list of fields to sort. To indicate sorting direction, fields my prefixed with + (ascending) or - (descending, default), e.g. /sales-orders?sort=+id
 - `fields` — to retrieve a subset of fields.
-- `embed` — to expand embedded entities (ie.: inside of an article entity, expand silhouette code into the silhouette object). Implementing “expand” correctly is difficult, so do it with care.
+- `embed` — to expand embedded entities (inside of an article entity, expand silhouette code into the silhouette object). Implementing “expand” correctly is difficult, so do it with care.
 
 ## SHOULD: Prefer Hyphenated-Pascal-Case for HTTP header Fields
 
-This is for consistency in your documentation (most other headers follow this convention). Avoid camelCase (without hyphens). Exceptions are common abbreviations like “ID.”
+This is for consistency in your documentation (most other headers follow this convention). Avoid `camelCase` (without hyphens). Exceptions are common abbreviations like “ID.”
 
 Examples:
 

content/api/resources.md

@@ -60,4 +60,4 @@ To keep maintenance and service evolution manageable, we should follow "function
 
 ## SHOULD: Limit number of Sub-Resource Levels
 
-There are main resources (with root url paths) and sub-resources (or “nested” resources with non-root urls paths). Use sub-resources if their life cycle is (loosely) coupled to the main resource, i.e. the main resource works as collection resource of the subresource entities. You should use <= 3 sub-resource (nesting) levels -- more levels increase API complexity and url path length. (Remember, some popular web browsers do not support URLs of more than 2000 characters)
+There are main resources (with root url paths) and sub-resources (or “nested” resources with non-root urls paths). Use sub-resources if their life cycle is (loosely) coupled to the main resource, i.e. the main resource works as collection resource of the `subresource` entities. You should use <= 3 sub-resource (nesting) levels -- more levels increase API complexity and url path length. (Remember, some popular web browsers do not support URLs of more than 2000 characters)