REST endpoint documentation (OHDSI#2118)

Co-authored-by: Adam Black <[email protected]> Co-authored-by: Adam Black <[email protected]> Co-authored-by: Chris Knoll <[email protected]>
ww166 · Oct 6, 2022 · e4230e5 · e4230e5
1 parent a475311
commit e4230e5
Show file tree

Hide file tree

Showing 31 changed files with 2,957 additions and 758 deletions.
diff --git a/README.md b/README.md
@@ -14,7 +14,11 @@ OHDSI WebAPI contains all OHDSI RESTful services that can be called from OHDSI a
 
 ## Technology
 
-OHDSI WebAPI is a Java 8 web application that utilizes a database (PostgreSQL, SQL Server or Oracle) for storage.
+OHDSI WebAPI is a Java 8 web application that utilizes a PostgreSQL database for storage.
+
+## API Documentation
+
+The API Documentation is found at [http://webapidoc.ohdsi.org/](http://webapidoc.ohdsi.org/)
 
 ## System Requirements & Installation
 

diff --git a/src/main/java/org/ohdsi/webapi/cohortcharacterization/CcController.java b/src/main/java/org/ohdsi/webapi/cohortcharacterization/CcController.java
@@ -105,6 +105,13 @@ public CcController(
         FeatureExtraction.init(null);
     }
 
+    /**
+     * Create a new cohort characterization
+     *
+     * @param dto A cohort characterization JSON definition (name, cohorts, featureAnalyses, etc.)
+     * @return The cohort characterization definition passed in as input
+     * with additional fields (createdDate, hasWriteAccess, tags, id, hashcode).
+     */
     @POST
     @Path("/")
     @Produces(MediaType.APPLICATION_JSON)
@@ -115,6 +122,12 @@ public CohortCharacterizationDTO create(final CohortCharacterizationDTO dto) {
         return conversionService.convert(createdEntity, CohortCharacterizationDTO.class);
     }
 
+    /**
+     * Create a copy of an existing cohort characterization
+     *
+     * @param id An existing cohort characterization id
+     * @return The cohort characterization definition of the newly created copy
+     */
     @POST
     @Path("/{id}")
     @Produces(MediaType.APPLICATION_JSON)
@@ -128,6 +141,11 @@ public CohortCharacterizationDTO copy(@PathParam("id") final Long id) {
         return create(dto);
     }
 
+    /**
+     * Get information about the cohort characterization analyses in WebAPI
+     *
+     * @return A json object with information about the characterization analyses in WebAPI.
+     */
     @GET
     @Path("/")
     @Produces(MediaType.APPLICATION_JSON)
@@ -140,6 +158,11 @@ public Page<CcShortDTO> list(@Pagination Pageable pageable) {
         });
     }
 
+    /**
+     * Get the design specification for every cohort-characterization analysis in WebAPI.
+     *
+     * @return A json object with all characterization design specifications.
+     */
     @GET
     @Path("/design")
     @Produces(MediaType.APPLICATION_JSON)
@@ -148,6 +171,12 @@ public Page<CohortCharacterizationDTO> listDesign(@Pagination Pageable pageable)
         return service.getPageWithLinkedEntities(pageable).map(this::convertCcToDto);
     }
 
+    /**
+     * Get metadata about a cohort characterization.
+     *
+     * @param id The id for an existing cohort characterization
+     * @return name, createdDate, tags, etc for a single cohort characterization.
+     */
     @GET
     @Path("/{id}")
     @Produces(MediaType.APPLICATION_JSON)
@@ -156,6 +185,12 @@ public CcShortDTO get(@PathParam("id") final Long id) {
         return convertCcToShortDto(service.findById(id));
     }
 
+    /**
+     * Get the complete design specification for a single cohort characterization.
+     *
+     * @param id The id for an existing cohort characterization
+     * @return JSON containing the cohort characterization specification
+     */
     @GET
     @Path("/{id}/design")
     @Produces(MediaType.APPLICATION_JSON)
@@ -166,6 +201,15 @@ public CohortCharacterizationDTO getDesign(@PathParam("id") final Long id) {
         return convertCcToDto(cc);
     }
 
+    /**
+     * Check if a cohort characterization with the same name exists
+     *
+     * <p>This endpoint is used to check that a desired name for a characterization does not already exist in WebAPI</p>
+     *
+     * @param id The id for a new characterization that does not currently exist in WebAPI
+     * @param name The desired name for the new cohort characterization
+     * @return The number of existing characterizations with the same name that was passed as a query parameter
+     */
     @GET
     @Path("/{id}/exists")
     @Produces(MediaType.APPLICATION_JSON)
@@ -174,6 +218,11 @@ public int getCountCcWithSameName(@PathParam("id") @DefaultValue("0") final long
         return service.getCountCcWithSameName(id, name);
     }
 
+    /**
+     * Remove a characterization from WebAPI
+     *
+     * @param id The id for a characterization that currently exists in WebAPI
+     */
     @DELETE
     @Path("/{id}")
     @Produces(MediaType.APPLICATION_JSON)
@@ -189,7 +238,7 @@ private CohortCharacterizationDTO convertCcToDto(final CohortCharacterizationEnt
     private CcShortDTO convertCcToShortDto(final CohortCharacterizationEntity entity) {
         return conversionService.convert(entity, CcShortDTO.class);
     }
-    
+
     @PUT
     @Path("/{id}")
     @Produces(MediaType.APPLICATION_JSON)
@@ -202,6 +251,14 @@ public CohortCharacterizationDTO update(@PathParam("id") final Long id, final Co
         return conversionService.convert(updatedEntity, CohortCharacterizationDTO.class);
     }
 
+    /**
+     * Add a new cohort characterization analysis to WebAPI
+     *
+     * @chrisknoll this endpoint did not work when I tried it.
+     *
+     * @param dto A cohort characterization definition
+     * @return The same cohort characterization definition that was passed as input
+     */
     @POST
     @Path("/import")
     @Produces(MediaType.APPLICATION_JSON)
@@ -213,6 +270,12 @@ public CohortCharacterizationDTO doImport(final CcExportDTO dto) {
         return conversionService.convert(service.importCc(entity), CohortCharacterizationDTO.class);
     }
 
+    /**
+     * Get a cohort characterization definition
+     *
+     * @param id The id of an existing cohort characterization definition
+     * @return JSON containing the cohort characterization definition
+     */
     @GET
     @Path("/{id}/export")
     @Produces(MediaType.APPLICATION_JSON)
@@ -221,6 +284,11 @@ public String export(@PathParam("id") final Long id) {
         return service.serializeCc(id);
     }
 
+    /**
+     * Get csv files containing concept sets used in a characterization analysis
+     * @param id The id for a cohort characterization analysis
+     * @return A zip file containing three csv files (mappedConcepts, includedConcepts, conceptSetExpression)
+     */
     @GET
     @Path("/{id}/export/conceptset")
     @Produces(MediaType.APPLICATION_OCTET_STREAM)
@@ -232,8 +300,13 @@ public Response exportConceptSets(@PathParam("id") final Long id) {
         ByteArrayOutputStream stream = ExportUtil.writeConceptSetExportToCSVAndZip(exportList);
         return HttpUtils.respondBinary(stream, String.format("cc_%d_export.zip", id));
     }
-
 
+    /**
+     * Check that a cohort characterization definition is correct
+     * @summary Check a cohort characterization definition
+     * @param characterizationDTO A cohort characterization definition object
+     * @return A list of warnings that is possibly empty
+     */
     @POST
     @Path("/check")
     @Produces(MediaType.APPLICATION_JSON)
@@ -242,6 +315,12 @@ public CheckResult runDiagnostics(CohortCharacterizationDTO characterizationDTO)
         return new CheckResult(checker.check(characterizationDTO));
     }
 
+    /**
+     * Generate a cohort characterization on a single data source
+     * @param id The id of an existing cohort characterization in WebAPI
+     * @param sourceKey The identifier for the data source to generate against
+     * @return A json object with information about the generation job included the status and execution id.
+     */
     @POST
     @Path("/{id}/generation/{sourceKey}")
     @Produces(MediaType.APPLICATION_JSON)
@@ -256,13 +335,24 @@ public JobExecutionResource generate(@PathParam("id") final Long id, @PathParam(
         return service.generateCc(id, sourceKey);
     }
 
+    /**
+     * Cancel a cohort characterization generation
+     * @param id The id of an existing cohort characterization
+     * @param sourceKey The sourceKey for the data source to generate against
+     * @return Status code
+     */
     @DELETE
     @Path("/{id}/generation/{sourceKey}")
     public Response cancelGeneration(@PathParam("id") final Long id, @PathParam("sourceKey") final String sourceKey) {
         service.cancelGeneration(id, sourceKey);
         return Response.ok().build();
     }
 
+    /**
+     * Get all generations for a cohort characterization
+     * @param id The id for an existing cohort characterization
+     * @return An array of all generations that includes the generation id, sourceKey, start and end times
+     */
     @GET
     @Path("/{id}/generation")
     @Produces(MediaType.APPLICATION_JSON)
@@ -274,6 +364,11 @@ public List<CommonGenerationDTO> getGenerationList(@PathParam("id") final Long i
                 info -> Collections.singletonMap(Constants.Variables.SOURCE, sourcesMap.get(info.getSourceKey())));
     }
 
+    /**
+     * Get generation information by generation id
+     * @param generationId The generation id to look up
+     * @return Data about the generation including the generation id, sourceKey, hashcode, start and end times
+     */
     @GET
     @Path("/generation/{generationId}")
     @Produces(MediaType.APPLICATION_JSON)
@@ -285,6 +380,10 @@ public CommonGenerationDTO getGeneration(@PathParam("generationId") final Long g
                 Collections.singletonMap(Constants.Variables.SOURCE, generationEntity.getSource()));
     }
 
+    /**
+     * Delete a cohort characterization generation
+     * @param generationId
+     */
     @DELETE
     @Path("/generation/{generationId}")
     @Produces(MediaType.APPLICATION_JSON)
@@ -293,6 +392,11 @@ public void deleteGeneration(@PathParam("generationId") final Long generationId)
         service.deleteCcGeneration(generationId);
     }
 
+    /**
+     * Get the definition of a cohort characterization for a given generation id
+     * @param generationId
+     * @return A cohort characterization definition
+     */
     @GET
     @Path("/generation/{generationId}/design")
     @Produces(MediaType.APPLICATION_JSON)
@@ -302,6 +406,12 @@ public CcExportDTO getGenerationDesign(
         return conversionService.convert(service.findDesignByGenerationId(generationId), CcExportDTO.class);
     }
 
+    /**
+     * Get the total number of analyses in a cohort characterization
+     *
+     * @param generationId
+     * @return The total number of analyses in the given cohort characterization
+     */
     @GET
     @Path("/generation/{generationId}/result/count")
     @Produces(MediaType.APPLICATION_JSON)
@@ -310,6 +420,13 @@ public Long getGenerationsResultsCount( @PathParam("generationId") final Long ge
         return service.getCCResultsTotalCount(generationId);
     }
 
+    /**
+     * Get cohort characterization results
+     * @param generationId id for generation
+     * @param thresholdLevel The max prevelance for a covariate. Covariates that occur in less than {threholdLevel}%
+     *                       of the cohort will not be returned. Default is 0.01 = 1%
+     * @return The complete set of characterization analyses filtered by the thresholdLevel parameter
+     */
     @GET
     @Path("/generation/{generationId}/result")
     @Produces(MediaType.APPLICATION_JSON)
@@ -318,7 +435,7 @@ public List<CcResult> getGenerationsResults(
             @PathParam("generationId") final Long generationId, @DefaultValue("0.01") @QueryParam("thresholdLevel") final float thresholdLevel) {
         return service.findResultAsList(generationId, thresholdLevel);
     }
-    
+
     @POST
     @Path("/generation/{generationId}/result")
     @Produces(MediaType.APPLICATION_JSON)
@@ -398,6 +515,13 @@ public List<CcPrevalenceStat> getPrevalenceStat(@PathParam("generationId") Long
         return stats;
     }
 
+    /**
+     * Download a cohort characterization R study package that can be used to run the characterization on an OMOP CDM from R
+     * @summary Download a cohort characterization R package
+     * @param analysisId id of the cohort characterization to convert to an R study package
+     * @param packageName The name of the R study package
+     * @return A zip file containing the cohort characterization R study package
+     */
     @GET
     @Path("{id}/download")
     @Consumes(MediaType.APPLICATION_JSON)