clean up high-level description

rst-api-spec.yaml.in

@@ -21,62 +21,19 @@ info:
     email: [email protected]
 
   description: |
-
-    _[RST-API Specification Home Page](https://icann.github.io/rst-api-spec/)_
-
-    _Last updated: #date %Y-%m-%d_
-
-    <br><br>
     The Registry System Testing (RST-API) provides a
     [RESTful](https://en.wikipedia.org/wiki/REST) interface to ICANN's [Registry
-    System Testing](https://www.icann.org/resources/registry-system-testing)
+    System Testing](https://www.icann.org/resources/registry-system-testing-v2.0)
     platform, which is used to conduct conformance tests of [critical registry
     functions](https://www.icann.org/registry-transition-processes-en#:~:text=Critical%20Functions:,registry%20data%20escrow)
     at various points during the lifecycle of a gTLD (before initial delegation,
     before the [transition to a new Registry Service
     Provider](https://www.icann.org/resources/material-subcontracting-arrangement),
-    or before the approval of new [registry
-    services](https://www.icann.org/resources/pages/rsep-2014-02-19-en)). It
-    will also used by the forthcoming [Registry Service Provider (RSP)
-    Pre-Evaluation Program](https://community.icann.org/display/SPIR/RSP+%7C+Registry+Service+Provider+Pre-Evaluation).
-
-    ### Workflow overview
-
-    The sequence diagram below describes the process by which tests are
-    scheduled, configured, and executed, in the context of the RSP Evaluation
-    Program:
+    before the approval of new [registry
+    services](https://www.icann.org/resources/pages/rsep-2014-02-19-en)), and
+    during [RSP evaluation](https://newgtldprogram.icann.org/en/application-rounds/round2/rsp).
 
-    * [High-level workflow](https://icann.github.io/rst-api-spec/etc/workflow.svg)
-
-    ### State diagram
-
-    Each test request object has a `status` property (see the `testStatus`
-    schema below) indicating its position in the test lifecycle. The following
-    state diagram describes this lifecycle:
-
-    * [State diagram](https://icann.github.io/rst-api-spec/etc/test-object-state-machine.svg)
-
-    ### Role-based access control
-
-    This API implements Role-Based Access Control, where access to certain
-    operations is restricted based on the role that is assigned to a user. For
-    example, external users cannot create new test request objects in the
-    production environment, but can in OT&E.
-
-    ### Authentication
-
-    All access to the API is authenticated using TLS certificates that are
-    authenticated using `TLSA` records published in the DNS. Test request
-    objects are associated with DNS hostnames; if a user presents a
-    certificate which matches one of the `TLSA` records published in the DNS at
-    one of these hostnames, it will be permitted to perform operations on that
-    object.
-
-    #### Internal users
-
-    Internal users must use a certificate that matches a `TLSA` record
-    found at a hard-coded DNS hostname *(the exact name is yet to be
-    determined)*.
+    _Last updated: #date %Y-%m-%d_.
 
     ### Change Log
 
@@ -226,8 +183,17 @@ info:
       * Add this change log.
       * Minimise the delta between the internal and external view.
 
+    ### Authentication
+
+    All access to the API is authenticated using TLS certificates that are
+    authenticated using `TLSA` records published in the DNS. For more
+    information, please consult [the RST v2.0 page on the ICANN
+    website](https://www.icann.org/resources/registry-system-testing-v2.0/#authentication-and-access-control).
+
     _Copyright #date %Y ICANN. All rights reserved._
 
+    _[RST-API Specification Home Page](https://icann.github.io/rst-api-spec/)_
+
 servers:
   - url: https://rst-api.icann.org
     description: Production server address