rearrange gra-api-create (#41)

Author: derek-globus

changelog.d/20260302_160718_derek_rearrange_api_create_sc_47178.rst

@@ -0,0 +1,39 @@
+
+Added
+-----
+
+*   Add Access Role Control to ``gra api create``.
+
+    Usage Example:
+
+    .. code-block:: console
+
+        gra api create "My API" \
+            --target ./target-json-structure.json \
+            --description "My Cool API" \
+            --owner "urn:globus:auth:identity:0b8067fc-0bb4-46e4-b23d-3ad543624519" \
+            --admin "urn:globus:auth:identity:d86ff962-1b2a-4de8-8bde-7dc993494dcb" \
+            --admin "urn:globus:groups:id:b0d11f00-5701-480f-a523-5b03869dfdbc" \
+            --viewer "urn:globus:groups:id:ed3219c3-c4ef-4b04-932a-d00bf88ceea7"
+
+Changed
+-------
+
+*   Change the ``gra api create`` command to accept a target file, instead of
+    constructing one from a supplied openapi specification.
+
+    New Usage Example:
+
+    .. code-block:: console
+
+        gra api create "My API" \
+            --target ./target-json-structure.json \
+            --description "My Cool API"
+
+*   Change the ``gra api update`` command to accept a target file with the option
+    ``--target`` instead of ``target-file``.
+
+Development
+-----------
+
+*   Centralize registered api printing logic into a command-shared function.

src/globus_registered_api/commands/api/_common.py

@@ -0,0 +1,40 @@
+# This file is a part of globus-registered-api.
+# https://github.com/globus/globus-registered-api
+# Copyright 2025-2026 Globus <support@globus.org>
+# SPDX-License-Identifier: Apache-2.0
+
+import json
+
+import click
+from globus_sdk import GlobusHTTPResponse
+
+
+def echo_registered_api(response: GlobusHTTPResponse, format: str) -> None:
+    if format == "json":
+        click.echo(json.dumps(response.data, indent=2))
+    else:
+        click.echo(f"ID:             {response['id']}")
+        click.echo(f"Name:           {response['name']}")
+        click.echo(f"Description:    {response['description']}")
+        _echo_list("Owners:         ", response["roles"]["owners"])
+        _echo_list("Administrators: ", response["roles"]["administrators"])
+        _echo_list("Viewers:        ", response["roles"]["viewers"])
+        click.echo(f"Created:        {response['created_timestamp']}")
+        click.echo(f"Updated:        {response['updated_timestamp']}")
+
+
+def _echo_list(key: str, items: list[str]) -> None:
+    """
+    Print a list of items, indented to a common length (the length of the key).
+    """
+
+    if not items:
+        click.echo(f"{key}")
+        return
+
+    # Print the first item prefixed with the key.
+    prefix = key
+    for item in items:
+        click.echo(f"{prefix}{item}")
+        # Print subsequent items prefixed with spaces to align with the first item.
+        prefix = " " * len(key)

src/globus_registered_api/commands/api/create.py

@@ -4,45 +4,60 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import json
+import pathlib
 
 import click
 
 from globus_registered_api.clients import create_flows_client
+from globus_registered_api.commands.api._common import echo_registered_api
 from globus_registered_api.context import CLIContext
 from globus_registered_api.context import with_cli_context
-from globus_registered_api.domain import HTTP_METHODS
-from globus_registered_api.domain import TargetSpecifier
-from globus_registered_api.openapi import AmbiguousContentTypeError
-from globus_registered_api.openapi import OpenAPILoadError
-from globus_registered_api.openapi import TargetNotFoundError
-from globus_registered_api.openapi import process_target
 
 
 @click.command("create")
-@click.argument("openapi_spec")
-@click.argument("method", type=click.Choice(HTTP_METHODS, case_sensitive=False))
-@click.argument("route")
 @click.argument("name")
 @click.option(
-    "--content-type",
-    default="*",
-    help="Target content-type for request body (required if multiple exist)",
+    "--target",
+    required=True,
+    type=click.Path(exists=True, dir_okay=False, readable=True, path_type=pathlib.Path),
+    help="Filepath to a JSON object containing the target definition",
 )
 @click.option(
     "--description",
     required=True,
     help="Description for the registered API",
 )
+@click.option(
+    "--owner",
+    "owners",
+    multiple=True,
+    help="Set owner URN (can specify multiple, can only be set by owners)",
+)
+@click.option(
+    "--administrator",
+    "administrators",
+    multiple=True,
+    help="Set administrator URN (can specify multiple, can only be set by owners)",
+)
+@click.option(
+    "--viewer",
+    "viewers",
+    multiple=True,
+    help=(
+        "Set viewer URN (can specify multiple, can only be set by owners "
+        "and administrators)"
+    ),
+)
 @click.option("--format", type=click.Choice(["json", "text"]), default="text")
 @with_cli_context
 def create_command(
     ctx: CLIContext,
-    openapi_spec: str,
-    method: str,
-    route: str,
+    target: pathlib.Path,
     name: str,
-    content_type: str,
     description: str,
+    owners: tuple[str, ...],
+    administrators: tuple[str, ...],
+    viewers: tuple[str, ...],
     format: str,
 ) -> None:
     """
@@ -51,41 +66,23 @@ def create_command(
     Extracts a target endpoint from an OpenAPI spec and registers it with
     the Flows service.
 
-    OPENAPI_SPEC - A filepath or URL to an OpenAPI specification (JSON or YAML).
-
-    METHOD - Target API's HTTP method (e.g., get, post, put, delete).
-
-    ROUTE - Target API's route path (e.g., /items or /items/{item_id}).
-
-    NAME - Name for the registered API.
+    NAME - Name of the new registered API.
 
     Example:
 
     \b
-        gra api create ./spec.json get /items "My API" --description "My API"
+        gra api create  "My API"  --target ./target.json --description "My API"
     """
-    try:
-        target = TargetSpecifier.create(method, route, content_type)
-    except ValueError as e:
-        raise click.ClickException(str(e))
-
-    try:
-        result = process_target(openapi_spec, target)
-    except (OpenAPILoadError, TargetNotFoundError, AmbiguousContentTypeError) as e:
-        raise click.ClickException(str(e))
-
     flows_client = create_flows_client(ctx.globus_app)
 
+    target_content = json.loads(target.read_text())
     res = flows_client.create_registered_api(
         name=name,
         description=description,
-        target=result.to_dict(),
+        target=target_content,
+        owners=list(owners),
+        administrators=list(administrators),
+        viewers=list(viewers),
     )
 
-    if format == "json":
-        click.echo(json.dumps(res.data, indent=2))
-    else:
-        click.echo(f"ID:          {res['id']}")
-        click.echo(f"Name:        {res['name']}")
-        click.echo(f"Description: {res['description']}")
-        click.echo(f"Created:     {res['created_timestamp']}")
+    echo_registered_api(res, format)

src/globus_registered_api/commands/api/show.py

@@ -3,11 +3,10 @@
 # Copyright 2025-2026 Globus <support@globus.org>
 # SPDX-License-Identifier: Apache-2.0
 
-import json
-
 import click
 
 from globus_registered_api.clients import create_flows_client
+from globus_registered_api.commands.api._common import echo_registered_api
 from globus_registered_api.context import CLIContext
 from globus_registered_api.context import with_cli_context
 
@@ -24,11 +23,4 @@ def show_command(ctx: CLIContext, registered_api_id: str, format: str) -> None:
 
     res = flows_client.get_registered_api(registered_api_id)
 
-    if format == "json":
-        click.echo(json.dumps(res.data, indent=2))
-    else:
-        click.echo(f"ID:          {res['id']}")
-        click.echo(f"Name:        {res['name']}")
-        click.echo(f"Description: {res['description']}")
-        click.echo(f"Created:     {res['created_timestamp']}")
-        click.echo(f"Updated:     {res['updated_timestamp']}")
+    echo_registered_api(res, format)

src/globus_registered_api/commands/api/update.py

@@ -11,6 +11,7 @@
 import click
 
 from globus_registered_api.clients import create_flows_client
+from globus_registered_api.commands.api._common import echo_registered_api
 from globus_registered_api.context import CLIContext
 from globus_registered_api.context import with_cli_context
 
@@ -51,9 +52,9 @@
     help="Clear all viewers (can only be set by owners and administrators)",
 )
 @click.option(
-    "--target-file",
+    "--target",
     type=click.Path(exists=True, dir_okay=False, path_type=pathlib.Path),
-    help="Path to JSON file containing target definition",
+    help="Filepath to a JSON object containing the target definition",
 )
 @click.option("--format", type=click.Choice(["json", "text"]), default="text")
 @with_cli_context
@@ -67,7 +68,7 @@ def update_command(
     viewers: tuple[str, ...],
     no_administrators: bool,
     no_viewers: bool,
-    target_file: pathlib.Path | None,
+    target: pathlib.Path | None,
     format: str,
 ) -> None:
     """
@@ -101,25 +102,14 @@ def update_command(
         request["viewers"] = []
     elif viewers:
         request["viewers"] = list(set(viewers))
-    if target_file is not None:
+    if target is not None:
         try:
-            request["target"] = json.loads(target_file.read_text())
+            request["target"] = json.loads(target.read_text())
         except json.JSONDecodeError as e:
             raise click.UsageError(f"Invalid JSON in target file: {e}")
         except UnicodeDecodeError as e:
             raise click.UsageError(f"Unable to read target file: {e}")
 
     res = flows_client.update_registered_api(registered_api_id, **request)
 
-    if format == "json":
-        click.echo(json.dumps(res.data, indent=2))
-    else:
-        click.echo(f"ID:             {res['id']}")
-        click.echo(f"Name:           {res['name']}")
-        click.echo(f"Description:    {res['description']}")
-        click.echo(f"Owners:         {res['roles']['owners']}")
-        click.echo(f"Administrators: {res['roles']['administrators']}")
-        click.echo(f"Viewers:        {res['roles']['viewers']}")
-        click.echo(f"Created:        {res['created_timestamp']}")
-        if res.get("edited_timestamp"):
-            click.echo(f"Edited:         {res['edited_timestamp']}")
+    echo_registered_api(res, format)

src/globus_registered_api/extended_flows_client.py

@@ -128,19 +128,30 @@ def create_registered_api(
         name: str,
         description: str,
         target: dict[str, t.Any],
+        owners: list[str],
+        administrators: list[str],
+        viewers: list[str],
     ) -> GlobusHTTPResponse:
         """
         Create a new registered API.
 
         :param name: Name for the registered API
         :param description: Description for the registered API
         :param target: Target definition dict (from OpenAPITarget.to_dict())
+        :param owners: List of owner URNs.
+        :param administrators: List of administrator URNs.
+        :param viewers: List of viewer URNs.
         :return: Response containing the created registered API
         """
         body: dict[str, t.Any] = {
             "name": name,
             "description": description,
             "target": target,
+            "roles": {
+                "owners": owners,
+                "administrators": administrators,
+                "viewers": viewers,
+            },
         }
 
         return self.post("/registered_apis", data=body)