From 7f16ca2ca375bd1bc9b8971572897d348dd06386 Mon Sep 17 00:00:00 2001 From: Albert Louis Rossi Date: Fri, 10 Mar 2023 07:31:32 -0600 Subject: [PATCH] dcache-frontend: add more detailed description of request objects for bulk and stage Motivation: Tier 1 (KIT) requested we include more description of the request structure for the TAPE API Stage request in the Swagger page. Modification: Add description to Stage, but also to the generic Bulk request. Result: Happier users? Target: master Request: 8.2 Patch: https://rb.dcache.org/r/13917/ Requires-notes: yes Acked-by: Dmitry --- .../restful/resources/bulk/BulkResources.java | 16 ++++++++++------ .../resources/tape/ArchiveInfoResources.java | 2 +- .../restful/resources/tape/ReleaseResources.java | 2 +- .../restful/resources/tape/StageResources.java | 14 ++++++++++---- 4 files changed, 22 insertions(+), 12 deletions(-) diff --git a/modules/dcache-frontend/src/main/java/org/dcache/restful/resources/bulk/BulkResources.java b/modules/dcache-frontend/src/main/java/org/dcache/restful/resources/bulk/BulkResources.java index 47894aa2ed6..401c56b5586 100644 --- a/modules/dcache-frontend/src/main/java/org/dcache/restful/resources/bulk/BulkResources.java +++ b/modules/dcache-frontend/src/main/java/org/dcache/restful/resources/bulk/BulkResources.java @@ -208,12 +208,16 @@ public List getRequests( @Consumes({MediaType.APPLICATION_JSON}) @Produces(MediaType.APPLICATION_JSON) public Response submit( - @ApiParam(value = "Description of the request, which defines the following: " - + "target (list), target_prefix, activity, cancel_on_failure, " - + "clear_on_success, clear_on_failure, delay_clear, expand_directories " - + "(NONE, TARGETS, ALL), pre_store (store all targets first), " - + "and arguments (map of name:value " - + "pairs) if required.", required = true) + @ApiParam(value = "Description of the request, which defines the following:\n\n" + + "**target** - Array of file paths. Required.\n" + + "**target_prefix** - String path prefix, applied to all targets. Optional.\n" + + "**activity** - String, name of the activity (PIN, UNPIN, DELETE, UPDATE_QOS). Required.\n" + + "**cancel_on_failure** - Boolean. Optional, defaults to false.\n" + + "**clear_on_success** - Boolean, Optional, defaults to false.\n" + + "**clear_on_failure** - Boolean, Optional, defaults to false.\n" + + "**expand_directories** - String (NONE, TARGETS, ALL). Optional, defaults to NONE\n" + + "**pre_store** - Boolean (store all targets first, including recursively discovered paths). Optional, defaults to false.\n" + + "**arguments** - Object (map) of name:value pairs. Optional, specific to activity.", required = true) String requestPayload) { Subject subject = getSubject(); Restriction restriction = getRestriction(); diff --git a/modules/dcache-frontend/src/main/java/org/dcache/restful/resources/tape/ArchiveInfoResources.java b/modules/dcache-frontend/src/main/java/org/dcache/restful/resources/tape/ArchiveInfoResources.java index 38e0034593b..fa856cb1319 100644 --- a/modules/dcache-frontend/src/main/java/org/dcache/restful/resources/tape/ArchiveInfoResources.java +++ b/modules/dcache-frontend/src/main/java/org/dcache/restful/resources/tape/ArchiveInfoResources.java @@ -126,7 +126,7 @@ public final class ArchiveInfoResources { @Consumes({MediaType.APPLICATION_JSON}) @Produces(MediaType.APPLICATION_JSON) public List getArchiveInfo( - @ApiParam(value = "List of paths for which to return archive info (file locality).", + @ApiParam(value = "Array of paths for which to return archive info (file locality).", required = true) String requestPayload) { diff --git a/modules/dcache-frontend/src/main/java/org/dcache/restful/resources/tape/ReleaseResources.java b/modules/dcache-frontend/src/main/java/org/dcache/restful/resources/tape/ReleaseResources.java index ef78e38e216..915a2bc7c3f 100644 --- a/modules/dcache-frontend/src/main/java/org/dcache/restful/resources/tape/ReleaseResources.java +++ b/modules/dcache-frontend/src/main/java/org/dcache/restful/resources/tape/ReleaseResources.java @@ -133,7 +133,7 @@ public final class ReleaseResources { @Produces(MediaType.APPLICATION_JSON) public Response release( @PathParam("id") String id, - @ApiParam(value = "List of file paths to release. If any path does not belong to the " + @ApiParam(value = "Array of file paths to release. If any path does not belong to the " + "stage request corresponding to the id, this request will fail.", required = true) String requestPayload) { diff --git a/modules/dcache-frontend/src/main/java/org/dcache/restful/resources/tape/StageResources.java b/modules/dcache-frontend/src/main/java/org/dcache/restful/resources/tape/StageResources.java index 0e584382aef..c578b5a6a6f 100644 --- a/modules/dcache-frontend/src/main/java/org/dcache/restful/resources/tape/StageResources.java +++ b/modules/dcache-frontend/src/main/java/org/dcache/restful/resources/tape/StageResources.java @@ -249,10 +249,16 @@ public Response cancel( @Consumes({MediaType.APPLICATION_JSON}) @Produces(MediaType.APPLICATION_JSON) public Response submit( - @ApiParam(value = "Description of the request, which consists of a list of file objects " - + "containing path, optional diskLifetime, and targetedMetadata. The latter is keyed " - + "to the sitename-from-well-known, and contains a map/object with site " - + "and implementation-specific attributes.", required = true) + @ApiParam(value = "Request structure:\n\n" + + "**files** - Array of File objects. Required.\n" + + "File object structure:\n" + + "**path**: - String. Path of the file. Duplicates will be sanitized. Required.\n" + + "**diskLifetime**: - String of ISO 8601 format. Duration after which the replica is considered no longer needed." + + " Optional (defaults to system default for pin lifetime).\n" + + "**targetdMetadata** - targeted metadata object. Keyed to the sitename-from-well-known, " + + "and contains a map/object with site and implementation-specific attributes. " + + "Currently ignored by dCache.\n" + + "See further https://docs.google.com/document/d/1Zx_H5dRkQRfju3xIYZ2WgjKoOvmLtsafP2pKGpHqcfY/edit#heading=h.93yzfvog73oc.", required = true) String requestPayload) { Subject subject = getSubject(); Restriction restriction = getRestriction();