Drafts a template for API object definitions

shared/api-definitions-ex.asciidoc

@@ -0,0 +1,73 @@
+[[sample-object]]
+=== Object1 API objects
+++++
+<titleabbrev>Object1</titleabbrev>
+++++
+// ***************************************
+// These pages complement API reference pages. They provide details about the
+// objects in API request bodies or response bodies.
+// They do not need to map 1:1 to API response bodies unless these pages are
+// automatically generated. 
+// These pages are typically nested under an API definitions page.
+// For an example of definitions that map specific objects to APIs, see:
+// https://www.elastic.co/guide/en/cloud-enterprise/current/definitions.html
+// For an example of definitions that apply to multiple APIs, see:
+// https://www.elastic.co/guide/en/elasticsearch/reference/master/api-definitions.html
+// ***************************************
+
+//Provide a brief description
+
+Is a cool thing.
+
+// Guidelines for API object documentation
+// ***************************************
+// * Use a definition list.
+// * Include the data type.
+// * Include default values as the last sentence of the first paragraph.
+// * Include a range of valid values, if applicable.
+// * For nested objects, link to a separate definition list.
+// ***************************************
+
+[float]
+[[sample-object-properties]]
+==== Properties
+
+////
+For example:
+
+`analysis_config`::
+  (object) The analysis configuration, which specifies how to analyze the data.
+  See <<ml-analysisconfig, analysis configuration objects>>.
+
+`job_id`::
+  (string) The unique identifier for the job. This identifier can contain
+  lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It
+  must start and end with alphanumeric characters.
+////
+
+[float]
+[[sample-object-example]]
+==== Example
+// Optional. Be aware that if you add examples they need to be kept up-to-date.
+
+////
+[source,js]
+----
+{
+      "job_id": "total-requests",
+      "analysis_config": {
+        "bucket_span": "10m",
+        "detectors": [
+          {
+            "detector_description": "Sum of total",
+            "function": "sum",
+            "field_name": "total",
+            "detector_index": 0
+          }
+        ],
+        "influencers": [ ]
+      },
+      ...
+    }
+----
+////