FORMAT: 1A HOST: http://polls.apiblueprint.org/ # Samwise Web API This document describes Samwise system WebAPI. Developers should refer to [this reference](https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf) for the guidelines about how to design good API. Please maintain good and coherent writing style. Dto naming convention For common Type, Event, Unit... definition name Dtos using syntax MyInitailizationDefinitionDto Sample related Dtos start with Sample, example SampleSomeDto # Data Structures ## ErrorDto (object) Definition of standard error + code: 403 (required, int) - HTTP error code + message: "User friendly description" (optional, string) - User friendly description ## SampleTypeDefinitionDto (object) Definition of SampleType , since this is definition of SampleType use name SampleTypeDefinitionDto + Id: 12345678 (number) - Unique key + Label: "myLabel" (string) - Free text for End User + LocalizationNameKey: "myName" (string) - Localized name key for the sample types + Localization Description Key: "myDescription" (string) - Localized description key for the sample types ## SampleEventDefinitionDto (object) Definition of Sample Event + Id: 12345678 (number) - Unique key + Label: "myLabel" (string) - Free text for End User + LocalizationNameKey: "myName" (string) - Localized name key for the sample event ## SampleStatusDefinitionDto (object) Definition of Sample Status + Id: 12345678 (number) - Unique key + Label: "myLabel" (string) - Free text for End User + LocalizationNameKey: "myName" (string) - Localized name key for the sample status ## SampleFlagDefinitionDto (object) Definition of Sample Flag + Id: 12345678 (number) - Unique key + Label: "myLabel" (string) - Free text for End User + LocalizationNameKey: "myName" (string) - Localized name key for the sample flag ## SampleUploadResultDto Sample upload Result + SampleId: 1 (optional, int) - Sample Id, returned if sample exists + BarCodeId: "1" (required, string) - BarCode Id + StatusCode: 1 (required, EnumFileUploadStatus) - Upload status ## SamplePropertiesDto (object) Definition of Sample Properties + ExternalSampleId: "12A4" (string, optional) - External Sample Id, such as parallel barcode from different system + ExternalSubjectId: "21az" (string,optional) - External Subject Id, such as parallel identifier from different system + NumberOfVisits: 1 (int, optional) - Number Of Visits (?) + TimePointUnitId: 1 (int, optional) - Identifier of unit used in Time Point + SampleAmountUnitId: 1 (int) - Sample Amount Unit Id, int (This relates to a table that contains all the sample units (volume,mass,concentration...)) + SampleAmount: 0.001 (number) - Sample amount + Aliquote: "A123" (optional, string) - aliquote string + SampleTypeId: 1 (required, int) - Sample Type identifier ## SampleDto (object) Definition of sample + SampleId: 123456789 (number, required) - Sample ID + BarCodeId: "1234567890" (string, required) - BarCode ID + SaveStatus: 1 (enum, optional) - Save status used where dto used as save response + SampleProperties: SamplePropertiesDto (SamplePropertiesDto, optional) - SamplePropertiesDto + ClientSampleId: 1 (int, optional) - Identifier of Sample ID received from client in request + Events: array[SampleEventDto] (array[SampleEventDto], optional) - Array of SampleEventDto ## SampleQueryDto (object) Definition of sample Query + Found: true (boolean, required) - True if sample found + ProjectId: 1 (int, optional) - ProjectId if sample found + Data: (SampleDto, required) - Sample Information , if sample is not found has SampleId or BarCodeId ## SampleEventDto (array) Decribes sample event, + EventId: 5 (int, required) - Event ID + Timestamp: "2050-02-18T21:00:42Z" (datetime, required) - Timestamp ## SampleMassCreateResponseDto In 29.4 api SaveResponseDto + Samples: array[SampleDto] (array[SampleDto], required) - Array of SampleDto, sample properties required in SampleDto + Subjects: array[SubjectStatusDto] (array[SubjectStatusDto], required) - Array of SubjectStatusDto ## SampleReceptionDto Sample Reception Dto + SubjectId: SubjectIdDto (required, subjectIdDto) + UseNextFreeSubjectId: true (optional, boolean) - If 'true', pick up SubjectIdSuffix from next free, regardless of SubjectIdSuffix field. + SampleData: SampleDto (required, SampleDto) + UseNextFreeSampleId: true (optional, boolean) - If 'true', pick up SampleId from next free, regardless of SubjectIdSuffix field. + UseNextFreeAliquote: true (optional, boolean) - If 'true', pick up Aliquote from next free, regardless of Aliquote field. + ContainerHierarchyPath: ContainerHierarchyPathDto (optional, boolean) ## SampleReceptionResponseDto Sample Reception Response Dto + SampleData: SampleDto (required, SampleDto) - Do not return details + SubjectId: SubjectIdDto (required, subjectIdDto) + ReceiveStatus: EnumSampleReceiveStatus (required, EnumSampleReceiveStatus) ## SubjectIdDto Dto for subject id + SubjectIdSuffix: 1234567890 (long, required) - SubjectIdSuffix + SubjectIdPrefix: "MyPrefix" (string, optional) - SubjectIdPrefix ## SubjectStatusDto Dto for subject status + SubjectId: SubjectIdDto (SubjectIdDto, required) - SubjectId + SubjectStatus: 1 (SubjectStatusEnumeration, required) - SubjectStatus as enumeration ## ProjectSubjectIdDto Describes Project Subject + ProjectId: 23 (int, required) - Project ID + SubjectId: SubjectIdDto ## ContainerHierarchyPathDto Describes container hierarchy path and sample location + ContainerIdPath: "23 /25 " (string, required) - Id Path set of IDs as String, " / " -separated + ContainerNamePath: "MyRack / MyBox " (string, required) - Path of Names (string), " / " -separated + Position: 1 (int, optional) - Number of cell where sample is located ## EnumSamplePlacing status code, e.g. 0 for OK, all checks passed. FOR NEW SAMPLES IT IS ALWAYS 0 (except 99. if we limit sample IDs somehow) If sample exists beforehand, perform checks and see if conditions are met (same codes as in other methods) •6 - Sample is already placed (has the location) •8- Sample status is "lost" •10 - Working set does not contain sample (can not be triggered if WorkingSetId=0) •11- Sample Id Not Found for the given projects •12- Sample is of wrong sample type •500 - Internal server Error ## EnumSampleReceiveStatus •1 - Sample Id Taken •2 - Out of Subject Ids •4 - can not assign aliquoute can it happen? •5 - Sample is already received and has Received timestamp set. •6 - Sample is already placed (has the location) •7- Sample ID empty (will not happen in our API but included for completeness). •8- Sample status is "lost" •9 - SampleID is tried to link to another (internal) subjectId than that it has been linked already before. •10 - Working set does not contain sample •11- Sample Id Not Found for the current project •12- Sample type mismatch •13- Sample Id Does not Exist ( trying to receive a sample that does not exist) •99 - Out of Free Sample Id •500 - Internal server Error ## EnumFileUploadStatus Status codes for file upload 1 - ok 2 - not exist # Group Sample Types, Events, Flags, Statuses API This section describes operations to retrieve sample types, events, statuses and flags. These operations provide client with information about sample related enumerations. ## Sample Types [/sampletypes] + Attributes (array[SampleTypeDefinitionDto]) ### Get All Sample Types [GET] Fetches all currently stored sample types items + Response 200 (application/json) + Attributes (array[SampleTypeDefinitionDto]) ## Sample Event, Status, Flag List [/sampleproperties] ### Get Sample Event , Status, Flags List [GET] Fetches all currently stored sample events, statuses and flags. Grouped in one request as they will be loaded on UI load. + Response 200 (application/json) + Attributes (object) + SampleEvents: array[SampleEventDefinitionDto] (array[SampleEventDefinitionDto], required) - Array of SampleEventDefinitionDto + SampleStatus: array[SampleStatusDefinitionDto] (array[SampleStatusDefinitionDto], required) - Array of SampleStatusDefinitionDto + SampleFlags: array[SampleFlagDefinitionDto] ( array[SampleFlagDefinitionDto], required) - Array of SampleFlagDefinitionDto + Response 404 (application/json) + Attributes (ErrorDto) # Group Sample API This section describes sample-related operations. ## Project Sample [/{projectid}/samples/{?id}{?barcodeid}{?detailed}] Operations of sample(s) of particular project + Parameters + projectid (required, int, `1`) ... Project ID + id (optional, string, `"124357891"`) ... Sample/Barcode ID to return full information + barcodeid (optional, boolean, `true`) ... If true use BarCodeId else SampleId + detailed (optional, boolean, , `true`) ... if defined and true, returns SampleProperties and Events sub-objects. Otherwise returns these fields as empty. ### Get project samples [GET] Returns specified sample if it belongs to given project. If no sampleId is specified, return all samples of given project. + Response 200 (application/json) + Attributes (array[SampleDto]) + Response 404 (application/json) + Attributes (ErrorDto) + Response 403 (application/json) + Attributes (ErrorDto) + Response 500 (application/json) + Attributes (ErrorDto) ### Create arbitrary set of samples inside given project [POST] This method facilitates the scenario, when a random set of samples is created, each sample can belong to arbitrary subject or created without subject attached. The entities must belong to one project. + Payload List of Samples (application/json) + Body { array[SampleDto] } + Response 200 (application/json) + Attributes (array[SampleDto]) + Response 404 (application/json) + Attributes (ErrorDto) + Response 403 (application/json) + Attributes (ErrorDto) + Response 500 (application/json) + Attributes (ErrorDto) ## Sample Mass operation [/{projectid}/samples/massoperation/{?id}{?barcodeid}] DRAFT COMMENT THIS PLEASE. HOW TO DO THIS WHEN MANY POST OPERATIONS TO THE SAME RESOURCE Sample mass operation of particular project + Parameters + projectid (required, int, `1`) ... Project ID + id (optional, string, `"124357891"`) ... Sample/Barcode ID to return full information + barcodeid (optional, boolean, `true`) ... If true use BarCodeId else SampleId ### Create set of samples for many subjects inside given project [POST] This method facilitates the scenario, when a fixed set of samples is created for number of subjects, so every subject receives the same set of samples. Subjects are created if not found. If no subject is given, samples set is created without attachment to any subject. The entities must belong to one project. + Payload List of Samples (application/json) + Body { Subjects: array[SubjectIdDto], Samples: array[SampleDto]} + Response 200 (application/json) + Attributes (object) + Samples: array[SampleDto] (array[SampleDto], required) - Array of SampleDto, sample properties required in SampleDto + Subjects: array[SubjectStatusDto] (array[SubjectStatusDto], required) - Array of SubjectStatusDto + Response 404 (application/json) + Attributes (ErrorDto) + Response 403 (application/json) + Attributes (ErrorDto) + Response 500 (application/json) + Attributes (ErrorDto) ## Sample Receive [/{projectid}/samples/receive/{?id}{?barcodeid}] DRAFT COMMENT THIS PLEASE. HOW TO DO THIS WHEN MANY POST OPERATIONS TO THE SAME RESOURCE Storing Received samples in database. This includes storing both "natural" and "additional" data about sample. + Parameters + projectid (required, int, `1`) ... Project ID + id (optional, string, `"124357891"`) ... Sample/Barcode ID to return full information + barcodeid (optional, boolean, `true`) ... If true use BarCodeId else SampleId ### Receive samples [POST] Storing Received samples in database. This includes storing both "natural" and "additional" data about sample. + Payload List of Samples (application/json) + Body { [SampleReceptionDto]) } + Response 200 (application/json) + Attributes (array[SampleReceptionResponseDto]) + Response 404 (application/json) + Attributes (ErrorDto) + Response 403 (application/json) + Attributes (ErrorDto) + Response 500 (application/json) + Attributes (ErrorDto) ## Sample list operations [/samples/list/{?detailed}{barcodeid}] Sample list operations without project connection + Parameters + detailed (optional, boolean) ... if defined and true, returns SampleProperties and Events sub-objects. Otherwise returns these fields as empty. + barcodeid (optional, boolean, `true`) ... If true use BarCodeId else SampleId ### Retrieve list of samples [POST] Retrieve a list of samples without project connection + Payload IdList (application/json) + Body { array[string] } + Response 200 (application/json) + Attributes (array[SampleDto]) + Response 404 (application/json) + Attributes (ErrorDto) + Response 403 (application/json) + Attributes (ErrorDto) + Response 500 (application/json) + Attributes (ErrorDto) ## Next free aliquote [/samples/{sampleid}/nextfreealiquote{?projectid}{subjectidsuffix}{subjectidprefix}] Resource for next free aliquote. Input data for various samples to check aliquote + Parameters + projectid (required, int) ... Project id + subjectidprefix (required, string) ...Prefix of SubjectId + subjectidsuffix (required, int) ...suffix of subjid ### Get next free aliquote [GET] Returns next free aliquote value. WHAT IS USED FOR MAKING NEW ALIQUOTE? IF SOME PARAMETERS ARE NOT NEEDED, REMOVE THEM FROM WebAPI. + Response 200 (application/json) Return object that mirrors all the input and adds next free aliquote. + Attributes (object) + ProjectId: 1 + SubjectIdPrefix: 'aa' + SubjectIdSuffix: 1 + SampleId: 1321431 + Aliquote : 'A1' + Response 412 (application/json) Length required if some parameters are missing from request + Attributes (ErrorDto) + Response 404 (application/json) if any of the project/subject/sample can not be found + Attributes (ErrorDto) + Response 500 (application/json) internal server error in all other cases + Attributes (ErrorDto) ## Aliquote status [/samples/{sampleid}/aliquote{?projectid}{subjectid}{aliquote}] Aliquote operation for sample. + Parameters + sampleid (required, number) ... Sample ID + projectid (required, int, `1`) ... ProjectId + subjectid (required, string, `MySub-1`) ... SubjectId + aliquote (required, string, `MyAli`) ... Aliquote ### Get aliquote status [GET] Reports if particular aliquote is taken or not. + Response 200 (application/json) + Attributes (object) + ProjectSubject: ProjectSubjectIdDto (required, ProjectSubjectIdDto) + SampleId: 1 (required, number) ... + Aliquote: "Ali" (required, string) + SampleFound: true (required, boolean) + SubjectFound: true (required, boolean) + AliquoteFree: true (required, boolean) + Response 401 (application/json) Length required if sampleid or subjectidsuffix or aliquote is empty + Attributes (ErrorDto) + Response 500 (application/json) internal server error in all other cases + Attributes (ErrorDto) ## Sample place [/samples/{sampleid}/place] ### Check can place sample [POST] Before a sample can be placed, we must be sure that it does not violate any pre-condition. If a pre-condition is violated, it is reported. See http://source.thl.fi/jira01/browse/SAMPLEMGMT-585 Also incorporate checks from sample receiving, see error codes list for all detectable errors + Payload IdList (application/json) + Body (object) + SampleId: 1 (required, string) - Sample Id or Barcode as string + ProjectIds: [1] (required, array[int]) - Project ids, List + WorkingSetId: 1 (required, int) - (0 if no working set) — used for checks + SampleTypeIds: [1] (required, array[int]) - Sample type ids List + UseAnd: true (required, boolean) -if true, project AND sampletype should match, otherwise OR + Containerid: 1 (optional, int) - ID of container to check to place in. Presently not used but will be needed later when we have rules for container's accepted sample types. + Response 200 (application/json) + Attributes (object) + SaveStatus: 1 (required, EnumSamplePlacing) - SamplePlacing enemeration + SampleId: 1 (required, number) - Sample id as in database + ContainerHierarchyPath: ContainerHierarchyPathDto (required, ContainerHierarchyPathDto) ## Sample file operations [/samples/file] Sample file operations ### Retrieve Sample Ids from uploaded Excel file [POST] Retriece BarCode Ids from excel file. missing sample IDs are limited to 1000 first problems in case of FILE UPLOAD ONLY, otherwise 100% of what was supplied in query. and statuses + Payload IdList (application/json) + Body (object) + BarCodeIds: ["1"] (required, array[string]) - BarCodeIds as Imported Excel file as multiPartContent in the HTTP POST + Response 200 (application/json) + Attributes (object) + BarCodeId: 1 (required, string) - BarCode Id + StatusCode: 1 (required, EnumFileUploadStatus) - Upload status + Response 500 (application/json) Internal Server Error + Attributes (ErrorDto) + Response 401 (application/json) Length required if no samples are in the file at all + Attributes (ErrorDto) + Response 412 (application/json) Precondition failed if header does not match the format + Attributes (ErrorDto) + Response 415 (application/json) Unsupported media type + Attributes (ErrorDto)