Enable API v3 only if OIDC is enabled and add usage examples

JIRA: RHELWF-7170
hluk · Jan 9, 2023 · 4901715 · 4901715
1 parent 66ee5ed
commit 4901715
Show file tree

Hide file tree

Showing 4 changed files with 66 additions and 23 deletions.
diff --git a/resultsdb/__init__.py b/resultsdb/__init__.py
@@ -109,14 +109,16 @@ def create_app(config_obj=None):
 
     register_handlers(app)
 
+    app.register_blueprint(main)
+    app.register_blueprint(api_v2, url_prefix="/api/v2.0")
+
     if app.config["AUTH_MODULE"] == "oidc":
         app.logger.info("OpenIDConnect authentication is enabled")
         enable_oidc(app)
+        app.register_blueprint(api_v3, url_prefix="/api/v3")
     else:
         app.logger.info("OpenIDConnect authentication is disabled")
 
-    register_blueprints(app)
-
     app.logger.debug("Finished ResultsDB initialization")
     return app
 
@@ -182,12 +184,6 @@ def not_found(error):
         return jsonify({"message": "Not found"}), 404
 
 
-def register_blueprints(app):
-    app.register_blueprint(main)
-    app.register_blueprint(api_v2, url_prefix="/api/v2.0")
-    app.register_blueprint(api_v3, url_prefix="/api/v3")
-
-
 def enable_oidc(app):
     with open(app.config["OIDC_CLIENT_SECRETS"]) as client_secrets_file:
         client_secrets = json.load(client_secrets_file)

diff --git a/resultsdb/controllers/api_v3.py b/resultsdb/controllers/api_v3.py
@@ -128,7 +128,6 @@ def index():
     )
     return render_template(
         "api_v3.html",
-        supports_oidc=app.config["AUTH_MODULE"] == "oidc",
         endpoints=endpoints,
         result_outcomes_extended=", ".join(result_outcomes_extended()),
     )
diff --git a/resultsdb/templates/api_v3.html b/resultsdb/templates/api_v3.html
@@ -6,19 +6,10 @@ <h1>ResultsDB API v3</h1>
 
 <p>This is API reference for ResultsDB REST API v3.</p>
 
-{% if supports_oidc %}
-<p>
-    This API supports OpenIDConnect authentication. You can get your access
-    token manually at
-    <a href="{{ url_for("login") }}">/auth/oidclogin</a>.
-</p>
-{% endif %}
-
-<p>List of valid test case outcomes: {{ result_outcomes_extended }}</p>
-
 Index:
 
 <p><ul>
+    <li><a href="#authentication">Authentication</a></li>
     {% for endpoint in endpoints %}
         <li>
             <a href="#{{ endpoint.name }}">
@@ -28,6 +19,55 @@ <h1>ResultsDB API v3</h1>
     {% endfor %}
 </ul></p>
 
+<section id="authentication">
+    <h2>
+        Authentication
+        <a class="anchor-link" href="#authentication">#</a>
+    </h2>
+
+    <p>
+    This API supports OpenIDConnect authentication. You can get your access token
+    manually at <a href="{{ url_for("login") }}">/auth/oidclogin</a>.
+    </p>
+
+    <p>
+    If you have a valid Kerberos ticket, you can retrieve the token using the
+    following Python code:
+    </p>
+
+<pre>
+import requests
+import requests_gssapi
+
+session = requests.Session()
+session.auth = requests_gssapi.HTTPKerberosAuth(mutual_authentication=requests_gssapi.OPTIONAL)
+response = session.get("{{ url_for("login", _external=True) }}")
+response.raise_for_status()
+token = response.json()["token"]
+</pre>
+
+    <p>
+    To publish a test result, pass the token to the "Authorization" HTTP header
+    in POST requests:
+    </p>
+
+<pre>
+response = session.post(
+    "{{ url_for("api_v3.results_brew-builds", _external=True) }}",
+    headers={"Authorization": f"Bearer {token}"},
+    json=test_result_data,
+)
+response.raise_for_status()
+</pre>
+
+    <p>Similar POST request with curl:</p>
+
+<pre>
+curl --json "$test_result_data" -H "Authorization: Bearer $token" \
+  {{ url_for("api_v3.results_brew-builds", _external=True) }}
+</pre>
+</section>
+
 {% for endpoint in endpoints %}
 <section id="{{ endpoint.name }}">
     <h2>
@@ -57,6 +97,9 @@ <h3>{{ type }} Parameters</h3>
                     <a class="anchor-link" href="#{{ endpoint.name }}/{{ name }}">#</a>
                     <p>
                         {{ endpoint.schema.properties[name].description | replace('\n\n', '<br>') | safe }}
+                        {% if name == "outcome" %}
+                            <br>Valid outcomes: {{ result_outcomes_extended }}
+                        {% endif %}
                     </p>
                 </section>
             </li>

diff --git a/testing/test_api_v3.py b/testing/test_api_v3.py
@@ -52,10 +52,15 @@ def brew_build_request_data(**kwargs):
 def test_api_v3_documentation(client):
     r = client.get("/api/v3/")
     assert r.status_code == 200, r.text
-    assert "POST /api/v3/results/brew-builds" in r.text
-    assert "POST /api/v3/results/redhat-container-images" in r.text
-    assert "GET /api/v3/permissions" in r.text
-    assert '<section id="results/brew-builds/outcome">' in r.text
+    assert "POST /api/v3/results/brew-builds" in r.text, r.text
+    assert "POST /api/v3/results/redhat-container-images" in r.text, r.text
+    assert "GET /api/v3/permissions" in r.text, r.text
+    assert '<section id="results/brew-builds/outcome">' in r.text, r.text
+    assert (
+        'curl --json "$test_result_data" -H "Authorization: Bearer $token" \\\n'
+        "  http://localhost/api/v3/results/brew-builds"
+    ) in r.text, r.text
+    assert 'response = session.get("http://localhost/auth/oidclogin")' in r.text, r.text
 
 
 def test_api_v3_create_brew_build(client):