Skip to content

Commit e4230e5

Browse files
anthonysenaAdam Blackablack3chrisknoll
authored
REST endpoint documentation (#2118)
Co-authored-by: Adam Black <adam.black@odysseusinc.com> Co-authored-by: Adam Black <ablack3@users.noreply.github.com> Co-authored-by: Chris Knoll <cknoll@ohdsi.org>
1 parent a475311 commit e4230e5

31 files changed

+2957
-758
lines changed

‎README.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,11 @@ OHDSI WebAPI contains all OHDSI RESTful services that can be called from OHDSI a
1414

1515
## Technology
1616

17-
OHDSI WebAPI is a Java 8 web application that utilizes a database (PostgreSQL, SQL Server or Oracle) for storage.
17+
OHDSI WebAPI is a Java 8 web application that utilizes a PostgreSQL database for storage.
18+
19+
## API Documentation
20+
21+
The API Documentation is found at [http://webapidoc.ohdsi.org/](http://webapidoc.ohdsi.org/)
1822

1923
## System Requirements & Installation
2024

‎src/main/java/org/ohdsi/webapi/cohortcharacterization/CcController.java

+127-3
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,13 @@ public CcController(
105105
FeatureExtraction.init(null);
106106
}
107107

108+
/**
109+
* Create a new cohort characterization
110+
*
111+
* @param dto A cohort characterization JSON definition (name, cohorts, featureAnalyses, etc.)
112+
* @return The cohort characterization definition passed in as input
113+
* with additional fields (createdDate, hasWriteAccess, tags, id, hashcode).
114+
*/
108115
@POST
109116
@Path("/")
110117
@Produces(MediaType.APPLICATION_JSON)
@@ -115,6 +122,12 @@ public CohortCharacterizationDTO create(final CohortCharacterizationDTO dto) {
115122
return conversionService.convert(createdEntity, CohortCharacterizationDTO.class);
116123
}
117124

125+
/**
126+
* Create a copy of an existing cohort characterization
127+
*
128+
* @param id An existing cohort characterization id
129+
* @return The cohort characterization definition of the newly created copy
130+
*/
118131
@POST
119132
@Path("/{id}")
120133
@Produces(MediaType.APPLICATION_JSON)
@@ -128,6 +141,11 @@ public CohortCharacterizationDTO copy(@PathParam("id") final Long id) {
128141
return create(dto);
129142
}
130143

144+
/**
145+
* Get information about the cohort characterization analyses in WebAPI
146+
*
147+
* @return A json object with information about the characterization analyses in WebAPI.
148+
*/
131149
@GET
132150
@Path("/")
133151
@Produces(MediaType.APPLICATION_JSON)
@@ -140,6 +158,11 @@ public Page<CcShortDTO> list(@Pagination Pageable pageable) {
140158
});
141159
}
142160

161+
/**
162+
* Get the design specification for every cohort-characterization analysis in WebAPI.
163+
*
164+
* @return A json object with all characterization design specifications.
165+
*/
143166
@GET
144167
@Path("/design")
145168
@Produces(MediaType.APPLICATION_JSON)
@@ -148,6 +171,12 @@ public Page<CohortCharacterizationDTO> listDesign(@Pagination Pageable pageable)
148171
return service.getPageWithLinkedEntities(pageable).map(this::convertCcToDto);
149172
}
150173

174+
/**
175+
* Get metadata about a cohort characterization.
176+
*
177+
* @param id The id for an existing cohort characterization
178+
* @return name, createdDate, tags, etc for a single cohort characterization.
179+
*/
151180
@GET
152181
@Path("/{id}")
153182
@Produces(MediaType.APPLICATION_JSON)
@@ -156,6 +185,12 @@ public CcShortDTO get(@PathParam("id") final Long id) {
156185
return convertCcToShortDto(service.findById(id));
157186
}
158187

188+
/**
189+
* Get the complete design specification for a single cohort characterization.
190+
*
191+
* @param id The id for an existing cohort characterization
192+
* @return JSON containing the cohort characterization specification
193+
*/
159194
@GET
160195
@Path("/{id}/design")
161196
@Produces(MediaType.APPLICATION_JSON)
@@ -166,6 +201,15 @@ public CohortCharacterizationDTO getDesign(@PathParam("id") final Long id) {
166201
return convertCcToDto(cc);
167202
}
168203

204+
/**
205+
* Check if a cohort characterization with the same name exists
206+
*
207+
* <p>This endpoint is used to check that a desired name for a characterization does not already exist in WebAPI</p>
208+
*
209+
* @param id The id for a new characterization that does not currently exist in WebAPI
210+
* @param name The desired name for the new cohort characterization
211+
* @return The number of existing characterizations with the same name that was passed as a query parameter
212+
*/
169213
@GET
170214
@Path("/{id}/exists")
171215
@Produces(MediaType.APPLICATION_JSON)
@@ -174,6 +218,11 @@ public int getCountCcWithSameName(@PathParam("id") @DefaultValue("0") final long
174218
return service.getCountCcWithSameName(id, name);
175219
}
176220

221+
/**
222+
* Remove a characterization from WebAPI
223+
*
224+
* @param id The id for a characterization that currently exists in WebAPI
225+
*/
177226
@DELETE
178227
@Path("/{id}")
179228
@Produces(MediaType.APPLICATION_JSON)
@@ -189,7 +238,7 @@ private CohortCharacterizationDTO convertCcToDto(final CohortCharacterizationEnt
189238
private CcShortDTO convertCcToShortDto(final CohortCharacterizationEntity entity) {
190239
return conversionService.convert(entity, CcShortDTO.class);
191240
}
192-
241+
193242
@PUT
194243
@Path("/{id}")
195244
@Produces(MediaType.APPLICATION_JSON)
@@ -202,6 +251,14 @@ public CohortCharacterizationDTO update(@PathParam("id") final Long id, final Co
202251
return conversionService.convert(updatedEntity, CohortCharacterizationDTO.class);
203252
}
204253

254+
/**
255+
* Add a new cohort characterization analysis to WebAPI
256+
*
257+
* @chrisknoll this endpoint did not work when I tried it.
258+
*
259+
* @param dto A cohort characterization definition
260+
* @return The same cohort characterization definition that was passed as input
261+
*/
205262
@POST
206263
@Path("/import")
207264
@Produces(MediaType.APPLICATION_JSON)
@@ -213,6 +270,12 @@ public CohortCharacterizationDTO doImport(final CcExportDTO dto) {
213270
return conversionService.convert(service.importCc(entity), CohortCharacterizationDTO.class);
214271
}
215272

273+
/**
274+
* Get a cohort characterization definition
275+
*
276+
* @param id The id of an existing cohort characterization definition
277+
* @return JSON containing the cohort characterization definition
278+
*/
216279
@GET
217280
@Path("/{id}/export")
218281
@Produces(MediaType.APPLICATION_JSON)
@@ -221,6 +284,11 @@ public String export(@PathParam("id") final Long id) {
221284
return service.serializeCc(id);
222285
}
223286

287+
/**
288+
* Get csv files containing concept sets used in a characterization analysis
289+
* @param id The id for a cohort characterization analysis
290+
* @return A zip file containing three csv files (mappedConcepts, includedConcepts, conceptSetExpression)
291+
*/
224292
@GET
225293
@Path("/{id}/export/conceptset")
226294
@Produces(MediaType.APPLICATION_OCTET_STREAM)
@@ -232,8 +300,13 @@ public Response exportConceptSets(@PathParam("id") final Long id) {
232300
ByteArrayOutputStream stream = ExportUtil.writeConceptSetExportToCSVAndZip(exportList);
233301
return HttpUtils.respondBinary(stream, String.format("cc_%d_export.zip", id));
234302
}
235-
236303

304+
/**
305+
* Check that a cohort characterization definition is correct
306+
* @summary Check a cohort characterization definition
307+
* @param characterizationDTO A cohort characterization definition object
308+
* @return A list of warnings that is possibly empty
309+
*/
237310
@POST
238311
@Path("/check")
239312
@Produces(MediaType.APPLICATION_JSON)
@@ -242,6 +315,12 @@ public CheckResult runDiagnostics(CohortCharacterizationDTO characterizationDTO)
242315
return new CheckResult(checker.check(characterizationDTO));
243316
}
244317

318+
/**
319+
* Generate a cohort characterization on a single data source
320+
* @param id The id of an existing cohort characterization in WebAPI
321+
* @param sourceKey The identifier for the data source to generate against
322+
* @return A json object with information about the generation job included the status and execution id.
323+
*/
245324
@POST
246325
@Path("/{id}/generation/{sourceKey}")
247326
@Produces(MediaType.APPLICATION_JSON)
@@ -256,13 +335,24 @@ public JobExecutionResource generate(@PathParam("id") final Long id, @PathParam(
256335
return service.generateCc(id, sourceKey);
257336
}
258337

338+
/**
339+
* Cancel a cohort characterization generation
340+
* @param id The id of an existing cohort characterization
341+
* @param sourceKey The sourceKey for the data source to generate against
342+
* @return Status code
343+
*/
259344
@DELETE
260345
@Path("/{id}/generation/{sourceKey}")
261346
public Response cancelGeneration(@PathParam("id") final Long id, @PathParam("sourceKey") final String sourceKey) {
262347
service.cancelGeneration(id, sourceKey);
263348
return Response.ok().build();
264349
}
265350

351+
/**
352+
* Get all generations for a cohort characterization
353+
* @param id The id for an existing cohort characterization
354+
* @return An array of all generations that includes the generation id, sourceKey, start and end times
355+
*/
266356
@GET
267357
@Path("/{id}/generation")
268358
@Produces(MediaType.APPLICATION_JSON)
@@ -274,6 +364,11 @@ public List<CommonGenerationDTO> getGenerationList(@PathParam("id") final Long i
274364
info -> Collections.singletonMap(Constants.Variables.SOURCE, sourcesMap.get(info.getSourceKey())));
275365
}
276366

367+
/**
368+
* Get generation information by generation id
369+
* @param generationId The generation id to look up
370+
* @return Data about the generation including the generation id, sourceKey, hashcode, start and end times
371+
*/
277372
@GET
278373
@Path("/generation/{generationId}")
279374
@Produces(MediaType.APPLICATION_JSON)
@@ -285,6 +380,10 @@ public CommonGenerationDTO getGeneration(@PathParam("generationId") final Long g
285380
Collections.singletonMap(Constants.Variables.SOURCE, generationEntity.getSource()));
286381
}
287382

383+
/**
384+
* Delete a cohort characterization generation
385+
* @param generationId
386+
*/
288387
@DELETE
289388
@Path("/generation/{generationId}")
290389
@Produces(MediaType.APPLICATION_JSON)
@@ -293,6 +392,11 @@ public void deleteGeneration(@PathParam("generationId") final Long generationId)
293392
service.deleteCcGeneration(generationId);
294393
}
295394

395+
/**
396+
* Get the definition of a cohort characterization for a given generation id
397+
* @param generationId
398+
* @return A cohort characterization definition
399+
*/
296400
@GET
297401
@Path("/generation/{generationId}/design")
298402
@Produces(MediaType.APPLICATION_JSON)
@@ -302,6 +406,12 @@ public CcExportDTO getGenerationDesign(
302406
return conversionService.convert(service.findDesignByGenerationId(generationId), CcExportDTO.class);
303407
}
304408

409+
/**
410+
* Get the total number of analyses in a cohort characterization
411+
*
412+
* @param generationId
413+
* @return The total number of analyses in the given cohort characterization
414+
*/
305415
@GET
306416
@Path("/generation/{generationId}/result/count")
307417
@Produces(MediaType.APPLICATION_JSON)
@@ -310,6 +420,13 @@ public Long getGenerationsResultsCount( @PathParam("generationId") final Long ge
310420
return service.getCCResultsTotalCount(generationId);
311421
}
312422

423+
/**
424+
* Get cohort characterization results
425+
* @param generationId id for generation
426+
* @param thresholdLevel The max prevelance for a covariate. Covariates that occur in less than {threholdLevel}%
427+
* of the cohort will not be returned. Default is 0.01 = 1%
428+
* @return The complete set of characterization analyses filtered by the thresholdLevel parameter
429+
*/
313430
@GET
314431
@Path("/generation/{generationId}/result")
315432
@Produces(MediaType.APPLICATION_JSON)
@@ -318,7 +435,7 @@ public List<CcResult> getGenerationsResults(
318435
@PathParam("generationId") final Long generationId, @DefaultValue("0.01") @QueryParam("thresholdLevel") final float thresholdLevel) {
319436
return service.findResultAsList(generationId, thresholdLevel);
320437
}
321-
438+
322439
@POST
323440
@Path("/generation/{generationId}/result")
324441
@Produces(MediaType.APPLICATION_JSON)
@@ -398,6 +515,13 @@ public List<CcPrevalenceStat> getPrevalenceStat(@PathParam("generationId") Long
398515
return stats;
399516
}
400517

518+
/**
519+
* Download a cohort characterization R study package that can be used to run the characterization on an OMOP CDM from R
520+
* @summary Download a cohort characterization R package
521+
* @param analysisId id of the cohort characterization to convert to an R study package
522+
* @param packageName The name of the R study package
523+
* @return A zip file containing the cohort characterization R study package
524+
*/
401525
@GET
402526
@Path("{id}/download")
403527
@Consumes(MediaType.APPLICATION_JSON)

0 commit comments

Comments
 (0)