add docs #8944

pdurbin · pdurbin · commit ae83c2790f82 · 2022-12-08T09:46:17.000-05:00
diff --git a/doc/sphinx-guides/source/admin/metadatacustomization.rst b/doc/sphinx-guides/source/admin/metadatacustomization.rst
@@ -386,12 +386,16 @@ Metadata Block Setup
 
 Now that you understand the TSV format used for metadata blocks, the next step is to attempt to make improvements to existing metadata blocks or create entirely new metadata blocks. For either task, you should have a Dataverse Software development environment set up for testing where you can drop the database frequently while you make edits to TSV files. Once you have tested your TSV files, you should consider making a pull request to contribute your improvement back to the community.
 
+.. _exploring-metadata-blocks:
+
 Exploring Metadata Blocks
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In addition to studying the TSV files themselves you might find the following highly experimental and subject-to-change API endpoints useful to understand the metadata blocks that have already been loaded into your Dataverse installation:
+In addition to studying the TSV files themselves you will probably find the :ref:`metadata-blocks-api` API helpful in getting a structured dump of metadata blocks in JSON format.
+
+There are also a few older, highly experimental, and subject-to-change API endpoints under the "admin" API documented below but the public API above is preferred.
 
-You can get a dump of metadata fields (yes, the output is odd, please open a issue) like this:
+You can get a dump of metadata fields like this:
 
 ``curl http://localhost:8080/api/admin/datasetfield``
 
diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst
@@ -3007,22 +3007,47 @@ The fully expanded example above (without environment variables) looks like this
 
   curl https://demo.dataverse.org/api/info/apiTermsOfUse
 
+.. _metadata-blocks-api:
+
 Metadata Blocks
 ---------------
 
+See also :ref:`exploring-metadata-blocks`.
+
 Show Info About All Metadata Blocks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-|CORS| Lists brief info about all metadata blocks registered in the system::
+|CORS| Lists brief info about all metadata blocks registered in the system.
+
+.. code-block:: bash
+
+  export SERVER_URL=https://demo.dataverse.org
+
+  curl $SERVER_URL/api/metadatablocks
+
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
 
-  GET http://$SERVER/api/metadatablocks
+  curl https://demo.dataverse.org/api/metadatablocks
 
 Show Info About Single Metadata Block
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-|CORS| Return data about the block whose ``identifier`` is passed. ``identifier`` can either be the block's id, or its name::
+|CORS| Return data about the block whose ``identifier`` is passed, including allowed controlled vocabulary values. ``identifier`` can either be the block's database id, or its name (i.e. "citation").
+
+.. code-block:: bash
+
+  export SERVER_URL=https://demo.dataverse.org
+  export IDENTIFIER=citation
+
+  curl $SERVER_URL/api/metadatablocks/$IDENTIFIER
+
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
 
-  GET http://$SERVER/api/metadatablocks/$identifier
+  curl https://demo.dataverse.org/api/metadatablocks/citation
 
 .. _Notifications:
 
