Merge pull request #254 from miharp/feat/http-api-migrate-250

feat: migrate HTTP API docs from openvox_8x to openvox-server_8x (#250)

Author: tuxmea

_data/nav/openvox-server_8x.yml

@@ -66,64 +66,98 @@
     link: tuning_guide.html
   - text: Scaling OpenVox Server with compilers
     link: scaling_puppet_server.html
-- text: Administrative API endpoints
+- text: HTTP API
   items:
-  - text: Environment cache
-    link: admin-api/v1/environment-cache.html
-  - text: JRuby pool
-    link: admin-api/v1/jruby-pool.html
-- text: CA API endpoints
-  items:
-  - text: Certificate
-    link: http_certificate.html
-  - text: Certificate signing request
-    link: http_certificate_request.html
-  - text: Certificate status
-    link: http_certificate_status.html
-  - text: Certificate revocation list
-    link: http_certificate_revocation_list.html
-- text: Server-specific Puppet API endpoints
-  items:
-  - text: Environment classes
-    link: puppet-api/v3/environment_classes.html
-  - text: Environment modules
-    link: puppet-api/v3/environment_modules.html
-  - text: Environment transports
-    link: puppet-api/v3/environment_transports.html
-  - text: Compile endpoint
-    link: puppet-api/v3/compile.html
-  - text: Static file content
-    link: puppet-api/v3/static_file_content.html
-  - text: File content
-    link: puppet-api/v3/file_content.html
-  - text: Tasks overview
-    link: puppet-api/v3/tasks.html
-  - text: Tasks details
-    link: puppet-api/v3/task_detail.html
-  - text: Plans overview
-    link: puppet-api/v3/plans.html
-  - text: Plans details
-    link: puppet-api/v3/plan_detail.html
-  - text: Catalog endpoint
-    link: puppet-api/v4/catalog.html
-- text: Status API endpoints
-  items:
-  - text: Services endpoint
-    link: status-api/v1/services.html
-  - text: Simple endpoint
-    link: status-api/v1/simple.html
-- text: Metrics
-  items:
-  - text: Monitoring OpenVox Server metrics
-    link: puppet_server_metrics.html
-  - text: HTTP client metrics
-    link: http_client_metrics.html
-  - text: Applying metrics to improve performance
-    link: puppet_server_metrics_performance.html
-  - text: v1 metrics API
-    link: metrics-api/v1/metrics_api.html
-  - text: v2 (Jolokia) metrics API
-    link: metrics-api/v2/metrics_api.html
+  - text: HTTP API overview
+    link: http_api_index.html
+  - text: PSON
+    link: pson.html
+  - text: Puppet v3 API
+    items:
+    - text: Catalog
+      link: http_catalog.html
+    - text: Node
+      link: http_node.html
+    - text: Facts
+      link: http_facts.html
+    - text: File bucket file
+      link: http_file_bucket_file.html
+    - text: File content
+      link: http_file_content.html
+    - text: File metadata
+      link: http_file_metadata.html
+    - text: Report
+      link: http_report.html
+    - text: Environments
+      link: http_environments.html
+  - text: Puppet v4 API
+    items:
+    - text: Catalog
+      link: puppet-api/v4/catalog.html
+  - text: CA v1 API
+    items:
+    - text: Certificate
+      link: http_certificate.html
+    - text: Certificate request
+      link: http_certificate_request.html
+    - text: Certificate status
+      link: http_certificate_status.html
+    - text: Certificate revocation list
+      link: http_certificate_revocation_list.html
+    - text: Certificate clean
+      link: http_certificate_clean.html
+    - text: Certificate expirations
+      link: http_certificate_expirations.html
+    - text: Certificate renewal
+      link: http_certificate_renewal.html
+    - text: Bulk certificate sign
+      link: http_certificate_sign.html
+  - text: Server-specific API
+    items:
+    - text: Environment classes
+      link: puppet-api/v3/environment_classes.html
+    - text: Environment modules
+      link: puppet-api/v3/environment_modules.html
+    - text: Environment transports
+      link: puppet-api/v3/environment_transports.html
+    - text: Compile endpoint
+      link: puppet-api/v3/compile.html
+    - text: Static file content
+      link: puppet-api/v3/static_file_content.html
+    - text: File content
+      link: puppet-api/v3/file_content.html
+    - text: Tasks overview
+      link: puppet-api/v3/tasks.html
+    - text: Tasks details
+      link: puppet-api/v3/task_detail.html
+    - text: Plans overview
+      link: puppet-api/v3/plans.html
+    - text: Plans details
+      link: puppet-api/v3/plan_detail.html
+  - text: Admin API
+    items:
+    - text: Environment cache
+      link: admin-api/v1/environment-cache.html
+    - text: JRuby pool
+      link: admin-api/v1/jruby-pool.html
+  - text: Status API
+    items:
+    - text: Services endpoint
+      link: status-api/v1/services.html
+    - text: Simple endpoint
+      link: status-api/v1/simple.html
+  - text: Metrics
+    items:
+    - text: Monitoring OpenVox Server metrics
+      link: puppet_server_metrics.html
+    - text: HTTP client metrics
+      link: http_client_metrics.html
+    - text: Applying metrics to improve performance
+      link: puppet_server_metrics_performance.html
+    - text: v1 metrics API
+      link: metrics-api/v1/metrics_api.html
+    - text: v2 (Jolokia) metrics API
+      link: metrics-api/v2/metrics_api.html
 - text: Developer information
   items:
   - text: Developer debugging

_data/nav/openvox_8x.yml

@@ -395,58 +395,8 @@
     link: "man/status.html"
 - text: HTTP API
   items:
-  - text: Index
-    link: "http_api/http_api_index.html"
-  - text: PSON
-    link: "http_api/pson.html"
-  - text: Catalog
-    link: "http_api/http_catalog.html"
-  - text: Node
-    link: "http_api/http_node.html"
-  - text: File bucket file
-    link: "http_api/http_file_bucket_file.html"
-  - text: File content
-    link: "http_api/http_file_content.html"
-  - text: File metadata
-    link: "http_api/http_file_metadata.html"
-  - text: Report
-    link: "http_api/http_report.html"
-  - text: Environments
-    link: "http_api/http_environments.html"
-  - text: Resource type
-    link: "http_api/http_resource_type.html"
-  - text: Status
-    link: "http_api/http_status.html"
-  - text: Certificate
-    link: "http_api/http_certificate.html"
-  - text: Certificate signing requests
-    link: "http_api/http_certificate_request.html"
-  - text: Certificate status
-    link: "http_api/http_certificate_status.html"
-  - text: Certificate revocation list
-    link: "http_api/http_certificate_revocation_list.html"
-  - text: catalog.json
-    link: "schemas/catalog.json"
-  - text: environments.json
-    link: "schemas/environments.json"
-  - text: error.json
-    link: "schemas/error.json"
-  - text: facts.json
-    link: "schemas/facts.json"
-  - text: file_metadata.json
-    link: "schemas/file_metadata.json"
-  - text: host.json
-    link: "schemas/host.json"
-  - text: json-meta-schema.json
-    link: "schemas/json-meta-schema.json"
-  - text: node.json
-    link: "schemas/node.json"
-  - text: report.json
-    link: "schemas/report.json"
-  - text: resource_type.json
-    link: "schemas/resource_type.json"
-  - text: status.json
-    link: "schemas/status.json"
+  - text: OpenVox Server HTTP API
+    link: "/openvox-server/latest/http_api_index.html"
 - text: SSL and certificates
   items:
   - text: Using an external CA

_includes/nav-item.html

@@ -28,7 +28,16 @@ <h2 class="text">{{ include.item.text }}</h2>
     </section>
   </div>
 {% elsif include.item.link %}
-  {% assign nav_item_url = include.item.link | prepend: nav_base %}
+  {%- comment -%}
+    Links starting with '/' are already absolute site paths. Prepending nav_base (which also
+    starts with '/') would produce a broken double-prefix like /openvox/latest//other/page.html.
+  {%- endcomment -%}
+  {% assign nav_link_first_char = include.item.link | slice: 0 %}
+  {% if nav_link_first_char == '/' %}
+    {% assign nav_item_url = include.item.link %}
+  {% else %}
+    {% assign nav_item_url = include.item.link | prepend: nav_base %}
+  {% endif %}
 
   <div class="VPSidebarItem level-{{ include.level }} is-link{% if nav_item_url == page.url %} is-active{% endif %}">
     <div class="item">

docs/_openvox-server_8x/http_api_index.markdown

@@ -25,12 +25,12 @@ All configuration endpoints are prefixed with `/puppet`, while all CA endpoints
 
 ### Authorization
 
-Authorization for `/puppet` and `/puppet-ca` endpoints is controlled with [OpenVox Server's `auth.conf` authorization system](./config_file_auth.html).
+Authorization for `/puppet` and `/puppet-ca` endpoints is controlled with [OpenVox Server's `auth.conf` authorization system](config_file_auth.html).
 
 ## OpenVox V3 HTTP API
 
 The OpenVox agent application uses several network services to manage systems. These services are all grouped under the `/puppet` API.
-Other tools can access these services and use the OpenVox Servers's data for other purposes.
+Other tools can access these services and use the OpenVox Server's data for other purposes.
 
 The V3 API contains endpoints of two types: those that are based on dispatching to OpenVox's internal "indirector" framework, and those that are not (namely the [environments endpoint](#environments-endpoint)).
 
@@ -44,52 +44,47 @@ Using this API requires significant understanding of how OpenVox's internal serv
 
 ### Configuration management services
 
-The OpenVox agent application directly uses these servcies to manage the configuration of a node.
+The OpenVox agent application directly uses these services to manage the configuration of a node.
 
 These endpoints accept payload formats formatted as JSON by default (MIME type of `application/json`), except for `File Content` and `File Bucket File`, which always use `application/octet-stream`.
 
 > **Note:** Legacy PSON (MIME type of `text/pson`) is still an available format, but should be used only as a fallback for binary content.
 
-- [Facts](/openvox/latest/http_api/http_facts.html)
-- [Catalog](/openvox/latest/http_api/http_catalog.html)
-- [Node](/openvox/latest/http_api/http_node.html)
-- [File bucket file](/openvox/latest/http_api/http_file_bucket_file.html)
-- [File content](/openvox/latest/http_api/http_file_content.html)
-- [File metadata](/openvox/latest/http_api/http_file_metadata.html)
-- [Report](/openvox/latest/http_api/http_report.html)
+- [Facts](http_facts.html)
+- [Catalog](http_catalog.html)
+- [Node](http_node.html)
+- [File bucket file](http_file_bucket_file.html)
+- [File content](http_file_content.html)
+- [File metadata](http_file_metadata.html)
+- [Report](http_report.html)
 
-### Informational services
-
-These services are not directly used by OpenVox agent, but can be used by other tools.
-
-- [Status](/openvox/latest/http_api/http_status.html)
-
-> **Note:** The [OpenVox Server status API](#openvox-server-specific-endpoints) provides more detail and features.
+> **Note:** The [Puppet v4 catalog API](puppet-api/v4/catalog.html) is preferred for new integrations. It does
+> not require facts to be submitted as part of the catalog request.
 
 ### Environments endpoint
 
-The `/puppet/v3/environments` endpoint uses a different format than the configuration management and informational services endpoints.
+The `/puppet/v3/environments` endpoint uses a different format than the configuration management endpoints.
 
 The endpoint accepts only payloads formatted as JSON, and responds with JSON (MIME type of `application/json`).
 
-- [Environments](/openvox/latest/http_api/http_environments.html)
+- [Environments](http_environments.html)
 
 ### OpenVox Server-specific endpoints
 
 OpenVox Server adds several unique endpoints of its own. They include these additional `/puppet/v3/` endpoints:
 
-- [Environment classes](./puppet-api/v3/environment_classes.html), at `/puppet/v3/environment_classes`
-- [Environment modules](./puppet-api/v3/environment_modules.html), at `/puppet/v3/environment_modules`
-- [Static file content](./puppet-api/v3/static_file_content.html), at `/puppet/v3/static_file_content`
+- [Environment classes](puppet-api/v3/environment_classes.html), at `/puppet/v3/environment_classes`
+- [Environment modules](puppet-api/v3/environment_modules.html), at `/puppet/v3/environment_modules`
+- [Static file content](puppet-api/v3/static_file_content.html), at `/puppet/v3/static_file_content`
 
 It also includes these unique APIs, with endpoints containing other URL prefixes:
 
-- [Status API](./status-api/v1/services.html), at `/status/v1/services`
-- [Metrics v1 (mbeans) API](./metrics-api/v1/metrics_api.html), at `/metrics/v1/mbeans`
-- [Metrics v2 (Jolokia) API](./metrics-api/v2/metrics_api.html), at `/metrics/v2/`
+- [Status API](status-api/v1/services.html), at `/status/v1/services`
+- [Metrics v1 (mbeans) API](metrics-api/v1/metrics_api.html), at `/metrics/v1/mbeans`
+- [Metrics v2 (Jolokia) API](metrics-api/v2/metrics_api.html), at `/metrics/v2/`
 - Admin API, at `/puppet-admin-api/v1/`:
-  - [Environment cache](./admin-api/v1/environment-cache.html), at `/puppet-admin-api/v1/environment-cache`
-  - [JRuby pool](./admin-api/v1/jruby-pool.html), at `/puppet-admin-api/v1/jruby-pool`
+  - [Environment cache](admin-api/v1/environment-cache.html), at `/puppet-admin-api/v1/environment-cache`
+  - [JRuby pool](admin-api/v1/jruby-pool.html), at `/puppet-admin-api/v1/jruby-pool`
 
 ### Error responses
 
@@ -109,7 +104,7 @@ Except for HEAD requests, error responses contain a body of a uniform JSON objec
 - `message`: (`String`) A human-readable message explaining the error.
 - `issue_kind`: (`String`) A unique label to identify the error class.
 
-OpenVOx provides a [JSON schema for error objects](/openvox/latest/schemas/error.json). Endpoints implemented by OpenVox Server have a different error schema:
+OpenVox provides a [JSON schema for error objects](/openvox/latest/schemas/error.json). Endpoints implemented by OpenVox Server have a different error schema:
 
 ```json
 {
@@ -136,18 +131,22 @@ The following documents specify what is available and how to interact with it.
 
 ### SSL certificate-related services
 
-These endpoints accept only plain-text payload formats. Historically, OpenVox has used the MIME type `s` to mean `text/plain`. In now uses `text/plain`, but continues to accept `s` as an equivalent.
+These endpoints accept only plain-text payload formats. Historically, OpenVox has used the MIME type `s` to mean `text/plain`. It now uses `text/plain`, but continues to accept `s` as an equivalent.
 
-- [Certificate](./http_certificate.html)
-- [Certificate Signing Requests](./http_certificate_request.html)
-- [Certificate Status](./http_certificate_status.html)
-- [Certificate Revocation List](./http_certificate_revocation_list.html)
+- [Certificate](http_certificate.html)
+- [Certificate Signing Requests](http_certificate_request.html)
+- [Certificate Status](http_certificate_status.html)
+- [Certificate Revocation List](http_certificate_revocation_list.html)
+- [Certificate Clean](http_certificate_clean.html)
+- [Certificate Expirations](http_certificate_expirations.html)
+- [Certificate Renewal](http_certificate_renewal.html)
+- [Bulk Certificate Sign](http_certificate_sign.html)
 
 ## Serialization formats
 
 OpenVox sends messages using several serialization formats. Not all REST services support all of the formats.
 
 - [JSON](https://tools.ietf.org/html/rfc7159)
-- [PSON](/openvox/latest/http_api/pson.html)
+- [PSON](pson.html) (deprecated — see the PSON page for details)
 
 `YAML` was supported in earlier versions of OpenVox, but is no longer for security reasons.