diff --git a/SampleService.html b/SampleService.html index 5281fc07..870263e5 100644 --- a/SampleService.html +++ b/SampleService.html @@ -1 +1 @@ -SampleService
/*
*A KBase module: SampleService
*
*Handles creating, updating, retriving samples and linking data to samples.
*
*Note that usage of the administration flags will be logged by the service.
*/
moduleSampleService{

/*
*A boolean value, 0 for false, 1 for true.
*/
typedefintboolean;

/*
*A timestamp in epoch milliseconds.
*/
typedefinttimestamp;

/*
*A user's username.
*/
typedefstringuser;

/*
*A SampleNode ID. Must be unique within a Sample and be less than 255 characters.
*/
typedefstringnode_id;

/*
*The type of a sample node. One of:
*BioReplicate - a biological replicate. Always at the top of the sample tree.
*TechReplicate - a technical replicate.
*SubSample - a sub sample that is not a technical replicate.
*/
typedefstringsamplenode_type;

/*
*A Sample ID. Must be globally unique. Always assigned by the Sample service.
*/
typedefstringsample_id;

/*
*A sample name. Must be less than 255 characters.
*/
typedefstringsample_name;

/*
*The version of a sample. Always > 0.
*/
typedefintversion;

/*
*A key in a metadata key/value pair. Less than 1000 unicode characters.
*/
typedefstringmetadata_key;

/*
*A key for a value associated with a piece of metadata. Less than 1000 unicode characters.
*Examples: units, value, species
*/
typedefstringmetadata_value_key;

/*
*Metadata attached to a sample.
*The UnspecifiedObject map values MUST be a primitive type - either int, float, string,
*or equivalent typedefs.
*/
typedefmapping<metadata_key,mapping<metadata_value_key,UnspecifiedObject>>metadata;

/*
*A KBase Workspace service Unique Permanent Address (UPA). E.g. 5/6/7 where 5 is the
*workspace ID, 6 the object ID, and 7 the object version.
*/
typedefstringws_upa;

/*
*An id for a unit of data within a KBase Workspace object. A single object may contain
*many data units. A dataid is expected to be unique within a single object. Must be less
*than 255 characters.
*/
typedefstringdata_id;

/*
*A node in a sample tree.
*id - the ID of the node.
*parent - the id of the parent node for the current node. BioReplicate nodes, and only
*BioReplicate nodes, do not have a parent.
*type - the type of the node.
*meta_controlled - metadata restricted by the sample controlled vocabulary and validators.
*meta_user - unrestricted metadata.
*/
typedefstructure{
node_idid;
node_idparent;
samplenode_typetype;
metadatameta_controlled;
metadatameta_user;
}SampleNode;

/*
*A Sample, consisting of a tree of subsamples and replicates.
*id - the ID of the sample.
*user - the user that saved the sample.
*node_tree - the tree(s) of sample nodes in the sample. The the roots of all trees must
*be BioReplicate nodes. All the BioReplicate nodes must be at the start of the list,
*and all child nodes must occur after their parents in the list.
*name - the name of the sample. Must be less than 255 characters.
*save_date - the date the sample version was saved.
*version - the version of the sample.
*/
typedefstructure{
sample_idid;
useruser;
list<SampleNode>node_tree;
sample_namename;
timestampsave_date;
versionversion;
}Sample;

/*
*Access control lists for a sample. Access levels include the privileges of the lower
*access levels.
*
*owner - the user that created and owns the sample.
*admin - users that can administrate (e.g. alter ACLs) the sample.
*write - users that can write (e.g. create a new version) to the sample.
*read - users that can view the sample.
*/
typedefstructure{
userowner;
list<user>admin;
list<user>write;
list<user>read;
}SampleACLs;

/*
*A Sample ID and version.
*id - the ID of the sample.
*version - the version of the sample.
*/
typedefstructure{
sample_idid;
versionversion;
}SampleAddress;

/*
*Parameters for creating a sample.
*If Sample.id is null, a new Sample is created along with a new ID.
*Otherwise, a new version of Sample.id is created. If Sample.id does not exist, an error
*is returned.
*Any incoming user, version or timestamp in the incoming sample is ignored.
*
*sample - the sample to save.
*prior_version - if non-null, ensures that no other sample version is saved between
*prior_version and the version that is created by this save. If this is not the case,
*the sample will fail to save.
*as_admin - run the method as a service administrator. The user must have full
*administration permissions.
*as_user - create the sample as a different user. Ignored if as_admin is not true. Neither
*the administrator nor the impersonated user need have permissions to the sample if a
*new version is saved.
*/
typedefstructure{
Samplesample;
intprior_version;
booleanas_admin;
useras_user;
}CreateSampleParams;

/*
*Create a new sample or a sample version.
*/
funcdefcreate_sample(CreateSampleParamsparams)returns(SampleAddressaddress)authenticationrequired;

/*
*get_sample parameters.
*id - the ID of the sample to retrieve.
*version - the version of the sample to retrieve, or the most recent sample if omitted.
*as_admin - get the sample regardless of ACLs as long as the user has administration read
*permissions.
*/
typedefstructure{
sample_idid;
versionversion;
booleanas_admin;
}GetSampleParams;

/*
*Get a sample. If the version is omitted the most recent sample is returned.
*/
funcdefget_sample(GetSampleParamsparams)returns(Samplesample)authenticationrequired;

/*
*get_sample_acls parameters.
*id - the ID of the sample to retrieve.
*as_admin - get the sample acls regardless of ACL contents as long as the user has
*administration read permissions.
*/
typedefstructure{
sample_idid;
booleanas_admin;
}GetSampleACLsParams;

/*
*Get a sample's ACLs.
*/
funcdefget_sample_acls(GetSampleACLsParamsparams)returns(SampleACLsacls)authenticationrequired;

/*
*replace_sample_acls parameters.
*
*id - the ID of the sample to modify.
*acls - the ACLs to set on the sample.
*as_admin - replace the sample acls regardless of ACL contents as long as the user has
*full administration permissions.
*/
typedefstructure{
sample_idid;
SampleACLsacls;
booleanas_admin;
}ReplaceSampleACLsParams;

/*
*Completely overwrite a sample's ACLs. Any current ACLs are replaced by the provided
*ACLs, even if empty, and gone forever.
*
*The sample owner cannot be changed via this method.
*/
funcdefreplace_sample_acls(ReplaceSampleACLsParamsparams)returns()authenticationrequired;

/*
*get_metadata_key_static_metadata parameters.
*
*keys - the list of metadata keys to interrogate.
*prefix -
*0 (the default) to interrogate standard metadata keys.
*1 to interrogate prefix metadata keys, but require an exact match to the prefix key.
*2 to interrogate prefix metadata keys, but any keys which are a prefix of the
*provided keys will be included in the results.
*/
typedefstructure{
list<metadata_key>keys;
intprefix;
}GetMetadataKeyStaticMetadataParams;

/*
*get_metadata_key_static_metadata results.
*
*static_metadata - the static metadata for the requested keys.
*/
typedefstructure{
metadatastatic_metadata;
}GetMetadataKeyStaticMetadataResults;

/*
*Get static metadata for one or more metadata keys.
*
*The static metadata for a metadata key is metadata *about* the key - e.g. it may
*define the key's semantics or denote that the key is linked to an ontological ID.
*
*The static metadata does not change without the service being restarted. Client caching is
*recommended to improve performance.
*/
funcdefget_metadata_key_static_metadata(GetMetadataKeyStaticMetadataParamsparams)returns(GetMetadataKeyStaticMetadataResultsresults)authenticationnone;

/*
*create_data_link parameters.
*
*upa - the workspace UPA of the object to be linked.
*dataid - the dataid of the data to be linked, if any, within the object. If omitted the
*entire object is linked to the sample.
*id - the sample id.
*version - the sample version.
*node - the sample node.
*update - if false (the default), fail if a link already exists from the data unit (the
*combination of the UPA and dataid). if true, expire the old link and create the new
*link unless the link is already to the requested sample node, in which case the
*operation is a no-op.
*as_admin - run the method as a service administrator. The user must have full
*administration permissions.
*as_user - create the link as a different user. Ignored if as_admin is not true. Neither
*the administrator nor the impersonated user need have permissions to the data or
*sample.
*/
typedefstructure{
ws_upaupa;
data_iddataid;
sample_idid;
versionversion;
node_idnode;
booleanupdate;
booleanas_admin;
useras_user;
}CreateDataLinkParams;

/*
*Create a link from a KBase Workspace object to a sample.
*
*The user must have admin permissions for the sample and write permissions for the
*Workspace object.
*/
funcdefcreate_data_link(CreateDataLinkParamsparams)returns()authenticationrequired;

/*
*expire_data_link parameters.
*
*upa - the workspace upa of the object from which the link originates.
*dataid - the dataid, if any, of the data within the object from which the link originates.
*Omit for links where the link is from the entire object.
*as_admin - run the method as a service administrator. The user must have full
*administration permissions.
*as_user - expire the link as a different user. Ignored if as_admin is not true. Neither
*the administrator nor the impersonated user need have permissions to the link if a
*new version is saved.
*/
typedefstructure{
ws_upaupa;
data_iddataid;
booleanas_admin;
useras_user;
}ExpireDataLinkParams;

/*
*Expire a link from a KBase Workspace object.
*
*The user must have admin permissions for the sample and write permissions for the
*Workspace object.
*/
funcdefexpire_data_link(ExpireDataLinkParamsparams)returns()authenticationrequired;

/*
*get_data_links_from_sample parameters.
*
*id - the sample ID.
*version - the sample version.
*effective_time - the effective time at which the query should be run - the default is
*the current time. Providing a time allows for reproducibility of previous results.
*as_admin - run the method as a service administrator. The user must have read
*administration permissions.
*/
typedefstructure{
sample_idid;
versionversion;
timestampeffective_time;
booleanas_admin;
}GetDataLinksFromSampleParams;

/*
*A data link from a KBase workspace object to a sample.
*
*upa - the workspace UPA of the linked object.
*dataid - the dataid of the linked data, if any, within the object. If omitted the
*entire object is linked to the sample.
*id - the sample id.
*version - the sample version.
*node - the sample node.
*createdby - the user that created the link.
*created - the time the link was created.
*expiredby - the user that expired the link, if any.
*expired - the time the link was expired, if at all.
*/
typedefstructure{
ws_upaupa;
data_iddataid;
sample_idid;
versionversion;
node_idnode;
usercreatedby;
timestampcreated;
userexpiredby;
timestampexpired;
}DataLink;

/*
*get_data_links_from_sample results.
*
*links - the links.
*effective_time - the time at which the query was run. This timestamp, if saved, can be
*used when running the method again to ensure reproducible results. Note that changes
*to workspace permissions may cause results to change over time.
*/
typedefstructure{
list<DataLink>links;
timestampeffective_time;
}GetDataLinksFromSampleResults;

/*
*Get data links to Workspace objects originating from a sample.
*
*The user must have read permissions to the sample. Only Workspace objects the user
*can read are returned.
*/
funcdefget_data_links_from_sample(GetDataLinksFromSampleParamsparams)returns(GetDataLinksFromSampleResultsresults)authenticationrequired;

/*
*get_data_links_from_data parameters.
*
*upa - the data UPA.
*effective_time - the effective time at which the query should be run - the default is
*the current time. Providing a time allows for reproducibility of previous results.
*as_admin - run the method as a service administrator. The user must have read
*administration permissions.
*/
typedefstructure{
ws_upaupa;
timestampeffective_time;
booleanas_admin;
}GetDataLinksFromDataParams;

/*
*get_data_links_from_data results.
*
*links - the links.
*effective_time - the time at which the query was run. This timestamp, if saved, can be
*used when running the method again to ensure reproducible results.
*/
typedefstructure{
list<DataLink>links;
timestampeffective_time;
}GetDataLinksFromDataResults;

/*
*Get data links to samples originating from Workspace data.
*
*The user must have read permissions to the workspace data.
*/
funcdefget_data_links_from_data(GetDataLinksFromDataParamsparams)returns(GetDataLinksFromDataResultsresults)authenticationrequired;

/*
*get_sample_via_data parameters.
*
*upa - the workspace UPA of the target object.
*id - the target sample id.
*version - the target sample version.
*/
typedefstructure{
ws_upaupa;
sample_idid;
versionversion;
}GetSampleViaDataParams;

/*
*Get a sample via a workspace object. Read permissions to a workspace object grants
*read permissions to all versions of any linked samples, whether the links are expired or
*not. This method allows for fetching samples when the user does not have explicit
*read access to the sample.
*/
funcdefget_sample_via_data(GetSampleViaDataParamsparams)returns(Samplesample)authenticationrequired;
};

Function Index

create_data_link
create_sample
expire_data_link
get_data_links_from_data
get_data_links_from_sample
get_metadata_key_static_metadata
get_sample
get_sample_acls
get_sample_via_data
replace_sample_acls

Type Index

boolean
CreateDataLinkParams
CreateSampleParams
data_id
DataLink
ExpireDataLinkParams
GetDataLinksFromDataParams
GetDataLinksFromDataResults
GetDataLinksFromSampleParams
GetDataLinksFromSampleResults
GetMetadataKeyStaticMetadataParams
GetMetadataKeyStaticMetadataResults
GetSampleACLsParams
GetSampleParams
GetSampleViaDataParams
metadata
metadata_key
metadata_value_key
node_id
ReplaceSampleACLsParams
Sample
sample_id
sample_name
SampleACLs
SampleAddress
SampleNode
samplenode_type
timestamp
user
version
ws_upa
\ No newline at end of file +SampleService
/*
*A KBase module: SampleService
*
*Handles creating, updating, retriving samples and linking data to samples.
*
*Note that usage of the administration flags will be logged by the service.
*/
moduleSampleService{

/*
*A boolean value, 0 for false, 1 for true.
*/
typedefintboolean;

/*
*A timestamp in epoch milliseconds.
*/
typedefinttimestamp;

/*
*A user's username.
*/
typedefstringuser;

/*
*A SampleNode ID. Must be unique within a Sample and be less than 255 characters.
*/
typedefstringnode_id;

/*
*The type of a sample node. One of:
*BioReplicate - a biological replicate. Always at the top of the sample tree.
*TechReplicate - a technical replicate.
*SubSample - a sub sample that is not a technical replicate.
*/
typedefstringsamplenode_type;

/*
*A Sample ID. Must be globally unique. Always assigned by the Sample service.
*/
typedefstringsample_id;

/*
*A sample name. Must be less than 255 characters.
*/
typedefstringsample_name;

/*
*The version of a sample. Always > 0.
*/
typedefintversion;

/*
*A key in a metadata key/value pair. Less than 1000 unicode characters.
*/
typedefstringmetadata_key;

/*
*A key for a value associated with a piece of metadata. Less than 1000 unicode characters.
*Examples: units, value, species
*/
typedefstringmetadata_value_key;

/*
*Metadata attached to a sample.
*The UnspecifiedObject map values MUST be a primitive type - either int, float, string,
*or equivalent typedefs.
*/
typedefmapping<metadata_key,mapping<metadata_value_key,UnspecifiedObject>>metadata;

/*
*A KBase Workspace service Unique Permanent Address (UPA). E.g. 5/6/7 where 5 is the
*workspace ID, 6 the object ID, and 7 the object version.
*/
typedefstringws_upa;

/*
*An id for a unit of data within a KBase Workspace object. A single object may contain
*many data units. A dataid is expected to be unique within a single object. Must be less
*than 255 characters.
*/
typedefstringdata_id;

/*
*A node in a sample tree.
*id - the ID of the node.
*parent - the id of the parent node for the current node. BioReplicate nodes, and only
*BioReplicate nodes, do not have a parent.
*type - the type of the node.
*meta_controlled - metadata restricted by the sample controlled vocabulary and validators.
*meta_user - unrestricted metadata.
*/
typedefstructure{
node_idid;
node_idparent;
samplenode_typetype;
metadatameta_controlled;
metadatameta_user;
}SampleNode;

/*
*A Sample, consisting of a tree of subsamples and replicates.
*id - the ID of the sample.
*user - the user that saved the sample.
*node_tree - the tree(s) of sample nodes in the sample. The the roots of all trees must
*be BioReplicate nodes. All the BioReplicate nodes must be at the start of the list,
*and all child nodes must occur after their parents in the list.
*name - the name of the sample. Must be less than 255 characters.
*save_date - the date the sample version was saved.
*version - the version of the sample.
*/
typedefstructure{
sample_idid;
useruser;
list<SampleNode>node_tree;
sample_namename;
timestampsave_date;
versionversion;
}Sample;

/*
*Access control lists for a sample. Access levels include the privileges of the lower
*access levels.
*
*owner - the user that created and owns the sample.
*admin - users that can administrate (e.g. alter ACLs) the sample.
*write - users that can write (e.g. create a new version) to the sample.
*read - users that can view the sample.
*/
typedefstructure{
userowner;
list<user>admin;
list<user>write;
list<user>read;
}SampleACLs;

/*
*A Sample ID and version.
*id - the ID of the sample.
*version - the version of the sample.
*/
typedefstructure{
sample_idid;
versionversion;
}SampleAddress;

/*
*Parameters for creating a sample.
*If Sample.id is null, a new Sample is created along with a new ID.
*Otherwise, a new version of Sample.id is created. If Sample.id does not exist, an error
*is returned.
*Any incoming user, version or timestamp in the incoming sample is ignored.
*
*sample - the sample to save.
*prior_version - if non-null, ensures that no other sample version is saved between
*prior_version and the version that is created by this save. If this is not the case,
*the sample will fail to save.
*as_admin - run the method as a service administrator. The user must have full
*administration permissions.
*as_user - create the sample as a different user. Ignored if as_admin is not true. Neither
*the administrator nor the impersonated user need have permissions to the sample if a
*new version is saved.
*/
typedefstructure{
Samplesample;
intprior_version;
booleanas_admin;
useras_user;
}CreateSampleParams;

/*
*Create a new sample or a sample version.
*/
funcdefcreate_sample(CreateSampleParamsparams)returns(SampleAddressaddress)authenticationrequired;

/*
*get_sample parameters.
*id - the ID of the sample to retrieve.
*version - the version of the sample to retrieve, or the most recent sample if omitted.
*as_admin - get the sample regardless of ACLs as long as the user has administration read
*permissions.
*/
typedefstructure{
sample_idid;
versionversion;
booleanas_admin;
}GetSampleParams;

/*
*Get a sample. If the version is omitted the most recent sample is returned.
*/
funcdefget_sample(GetSampleParamsparams)returns(Samplesample)authenticationrequired;

/*
*get_sample_acls parameters.
*id - the ID of the sample to retrieve.
*as_admin - get the sample acls regardless of ACL contents as long as the user has
*administration read permissions.
*/
typedefstructure{
sample_idid;
booleanas_admin;
}GetSampleACLsParams;

/*
*Get a sample's ACLs.
*/
funcdefget_sample_acls(GetSampleACLsParamsparams)returns(SampleACLsacls)authenticationrequired;

/*
*replace_sample_acls parameters.
*
*id - the ID of the sample to modify.
*acls - the ACLs to set on the sample.
*as_admin - replace the sample acls regardless of ACL contents as long as the user has
*full administration permissions.
*/
typedefstructure{
sample_idid;
SampleACLsacls;
booleanas_admin;
}ReplaceSampleACLsParams;

/*
*Completely overwrite a sample's ACLs. Any current ACLs are replaced by the provided
*ACLs, even if empty, and gone forever.
*
*The sample owner cannot be changed via this method.
*/
funcdefreplace_sample_acls(ReplaceSampleACLsParamsparams)returns()authenticationrequired;

/*
*get_metadata_key_static_metadata parameters.
*
*keys - the list of metadata keys to interrogate.
*prefix -
*0 (the default) to interrogate standard metadata keys.
*1 to interrogate prefix metadata keys, but require an exact match to the prefix key.
*2 to interrogate prefix metadata keys, but any keys which are a prefix of the
*provided keys will be included in the results.
*/
typedefstructure{
list<metadata_key>keys;
intprefix;
}GetMetadataKeyStaticMetadataParams;

/*
*get_metadata_key_static_metadata results.
*
*static_metadata - the static metadata for the requested keys.
*/
typedefstructure{
metadatastatic_metadata;
}GetMetadataKeyStaticMetadataResults;

/*
*Get static metadata for one or more metadata keys.
*
*The static metadata for a metadata key is metadata *about* the key - e.g. it may
*define the key's semantics or denote that the key is linked to an ontological ID.
*
*The static metadata does not change without the service being restarted. Client caching is
*recommended to improve performance.
*/
funcdefget_metadata_key_static_metadata(GetMetadataKeyStaticMetadataParamsparams)returns(GetMetadataKeyStaticMetadataResultsresults)authenticationnone;

/*
*create_data_link parameters.
*
*upa - the workspace UPA of the object to be linked.
*dataid - the dataid of the data to be linked, if any, within the object. If omitted the
*entire object is linked to the sample.
*id - the sample id.
*version - the sample version.
*node - the sample node.
*update - if false (the default), fail if a link already exists from the data unit (the
*combination of the UPA and dataid). if true, expire the old link and create the new
*link unless the link is already to the requested sample node, in which case the
*operation is a no-op.
*as_admin - run the method as a service administrator. The user must have full
*administration permissions.
*as_user - create the link as a different user. Ignored if as_admin is not true. Neither
*the administrator nor the impersonated user need have permissions to the data or
*sample.
*/
typedefstructure{
ws_upaupa;
data_iddataid;
sample_idid;
versionversion;
node_idnode;
booleanupdate;
booleanas_admin;
useras_user;
}CreateDataLinkParams;

/*
*A data link from a KBase workspace object to a sample.
*
*upa - the workspace UPA of the linked object.
*dataid - the dataid of the linked data, if any, within the object. If omitted the
*entire object is linked to the sample.
*id - the sample id.
*version - the sample version.
*node - the sample node.
*createdby - the user that created the link.
*created - the time the link was created.
*expiredby - the user that expired the link, if any.
*expired - the time the link was expired, if at all.
*/
typedefstructure{
ws_upaupa;
data_iddataid;
sample_idid;
versionversion;
node_idnode;
usercreatedby;
timestampcreated;
userexpiredby;
timestampexpired;
}DataLink;

/*
*create_data_link results.
*
*new_link - the new link.
*/
typedefstructure{
DataLinknew_link;
}CreateDataLinkResults;

/*
*Create a link from a KBase Workspace object to a sample.
*
*The user must have admin permissions for the sample and write permissions for the
*Workspace object.
*/
funcdefcreate_data_link(CreateDataLinkParamsparams)returns(CreateDataLinkResultsresults)authenticationrequired;

/*
*expire_data_link parameters.
*
*upa - the workspace upa of the object from which the link originates.
*dataid - the dataid, if any, of the data within the object from which the link originates.
*Omit for links where the link is from the entire object.
*as_admin - run the method as a service administrator. The user must have full
*administration permissions.
*as_user - expire the link as a different user. Ignored if as_admin is not true. Neither
*the administrator nor the impersonated user need have permissions to the link if a
*new version is saved.
*/
typedefstructure{
ws_upaupa;
data_iddataid;
booleanas_admin;
useras_user;
}ExpireDataLinkParams;

/*
*Expire a link from a KBase Workspace object.
*
*The user must have admin permissions for the sample and write permissions for the
*Workspace object.
*/
funcdefexpire_data_link(ExpireDataLinkParamsparams)returns()authenticationrequired;

/*
*get_data_links_from_sample parameters.
*
*id - the sample ID.
*version - the sample version.
*effective_time - the effective time at which the query should be run - the default is
*the current time. Providing a time allows for reproducibility of previous results.
*as_admin - run the method as a service administrator. The user must have read
*administration permissions.
*/
typedefstructure{
sample_idid;
versionversion;
timestampeffective_time;
booleanas_admin;
}GetDataLinksFromSampleParams;

/*
*get_data_links_from_sample results.
*
*links - the links.
*effective_time - the time at which the query was run. This timestamp, if saved, can be
*used when running the method again to ensure reproducible results. Note that changes
*to workspace permissions may cause results to change over time.
*/
typedefstructure{
list<DataLink>links;
timestampeffective_time;
}GetDataLinksFromSampleResults;

/*
*Get data links to Workspace objects originating from a sample.
*
*The user must have read permissions to the sample. Only Workspace objects the user
*can read are returned.
*/
funcdefget_data_links_from_sample(GetDataLinksFromSampleParamsparams)returns(GetDataLinksFromSampleResultsresults)authenticationrequired;

/*
*get_data_links_from_data parameters.
*
*upa - the data UPA.
*effective_time - the effective time at which the query should be run - the default is
*the current time. Providing a time allows for reproducibility of previous results.
*as_admin - run the method as a service administrator. The user must have read
*administration permissions.
*/
typedefstructure{
ws_upaupa;
timestampeffective_time;
booleanas_admin;
}GetDataLinksFromDataParams;

/*
*get_data_links_from_data results.
*
*links - the links.
*effective_time - the time at which the query was run. This timestamp, if saved, can be
*used when running the method again to ensure reproducible results.
*/
typedefstructure{
list<DataLink>links;
timestampeffective_time;
}GetDataLinksFromDataResults;

/*
*Get data links to samples originating from Workspace data.
*
*The user must have read permissions to the workspace data.
*/
funcdefget_data_links_from_data(GetDataLinksFromDataParamsparams)returns(GetDataLinksFromDataResultsresults)authenticationrequired;

/*
*get_sample_via_data parameters.
*
*upa - the workspace UPA of the target object.
*id - the target sample id.
*version - the target sample version.
*/
typedefstructure{
ws_upaupa;
sample_idid;
versionversion;
}GetSampleViaDataParams;

/*
*Get a sample via a workspace object. Read permissions to a workspace object grants
*read permissions to all versions of any linked samples, whether the links are expired or
*not. This method allows for fetching samples when the user does not have explicit
*read access to the sample.
*/
funcdefget_sample_via_data(GetSampleViaDataParamsparams)returns(Samplesample)authenticationrequired;
};

Function Index

create_data_link
create_sample
expire_data_link
get_data_links_from_data
get_data_links_from_sample
get_metadata_key_static_metadata
get_sample
get_sample_acls
get_sample_via_data
replace_sample_acls

Type Index

boolean
CreateDataLinkParams
CreateDataLinkResults
CreateSampleParams
data_id
DataLink
ExpireDataLinkParams
GetDataLinksFromDataParams
GetDataLinksFromDataResults
GetDataLinksFromSampleParams
GetDataLinksFromSampleResults
GetMetadataKeyStaticMetadataParams
GetMetadataKeyStaticMetadataResults
GetSampleACLsParams
GetSampleParams
GetSampleViaDataParams
metadata
metadata_key
metadata_value_key
node_id
ReplaceSampleACLsParams
Sample
sample_id
sample_name
SampleACLs
SampleAddress
SampleNode
samplenode_type
timestamp
user
version
ws_upa
\ No newline at end of file diff --git a/SampleService.spec b/SampleService.spec index 5da3e410..7d18a6b4 100644 --- a/SampleService.spec +++ b/SampleService.spec @@ -259,12 +259,46 @@ module SampleService { user as_user; } CreateDataLinkParams; + /* A data link from a KBase workspace object to a sample. + + upa - the workspace UPA of the linked object. + dataid - the dataid of the linked data, if any, within the object. If omitted the + entire object is linked to the sample. + id - the sample id. + version - the sample version. + node - the sample node. + createdby - the user that created the link. + created - the time the link was created. + expiredby - the user that expired the link, if any. + expired - the time the link was expired, if at all. + */ + typedef structure { + ws_upa upa; + data_id dataid; + sample_id id; + version version; + node_id node; + user createdby; + timestamp created; + user expiredby; + timestamp expired; + } DataLink; + + /* create_data_link results. + + new_link - the new link. + */ + typedef structure { + DataLink new_link; + } CreateDataLinkResults; + /* Create a link from a KBase Workspace object to a sample. The user must have admin permissions for the sample and write permissions for the Workspace object. */ - funcdef create_data_link(CreateDataLinkParams params) returns() authentication required; + funcdef create_data_link(CreateDataLinkParams params) returns(CreateDataLinkResults results) + authentication required; /* expire_data_link parameters. @@ -307,31 +341,6 @@ module SampleService { boolean as_admin; } GetDataLinksFromSampleParams; - /* A data link from a KBase workspace object to a sample. - - upa - the workspace UPA of the linked object. - dataid - the dataid of the linked data, if any, within the object. If omitted the - entire object is linked to the sample. - id - the sample id. - version - the sample version. - node - the sample node. - createdby - the user that created the link. - created - the time the link was created. - expiredby - the user that expired the link, if any. - expired - the time the link was expired, if at all. - */ - typedef structure { - ws_upa upa; - data_id dataid; - sample_id id; - version version; - node_id node; - user createdby; - timestamp created; - user expiredby; - timestamp expired; - } DataLink; - /* get_data_links_from_sample results. links - the links. diff --git a/lib/SampleService/SampleServiceClient.py b/lib/SampleService/SampleServiceClient.py index 0d900fe8..1040d511 100644 --- a/lib/SampleService/SampleServiceClient.py +++ b/lib/SampleService/SampleServiceClient.py @@ -290,6 +290,32 @@ def create_data_link(self, params, context=None): (A boolean value, 0 for false, 1 for true.), parameter "as_admin" of type "boolean" (A boolean value, 0 for false, 1 for true.), parameter "as_user" of type "user" (A user's username.) + :returns: instance of type "CreateDataLinkResults" (create_data_link + results. new_link - the new link.) -> structure: parameter + "new_link" of type "DataLink" (A data link from a KBase workspace + object to a sample. upa - the workspace UPA of the linked object. + dataid - the dataid of the linked data, if any, within the object. + If omitted the entire object is linked to the sample. id - the + sample id. version - the sample version. node - the sample node. + createdby - the user that created the link. created - the time the + link was created. expiredby - the user that expired the link, if + any. expired - the time the link was expired, if at all.) -> + structure: parameter "upa" of type "ws_upa" (A KBase Workspace + service Unique Permanent Address (UPA). E.g. 5/6/7 where 5 is the + workspace ID, 6 the object ID, and 7 the object version.), + parameter "dataid" of type "data_id" (An id for a unit of data + within a KBase Workspace object. A single object may contain many + data units. A dataid is expected to be unique within a single + object. Must be less than 255 characters.), parameter "id" of type + "sample_id" (A Sample ID. Must be globally unique. Always assigned + by the Sample service.), parameter "version" of type "version" + (The version of a sample. Always > 0.), parameter "node" of type + "node_id" (A SampleNode ID. Must be unique within a Sample and be + less than 255 characters.), parameter "createdby" of type "user" + (A user's username.), parameter "created" of type "timestamp" (A + timestamp in epoch milliseconds.), parameter "expiredby" of type + "user" (A user's username.), parameter "expired" of type + "timestamp" (A timestamp in epoch milliseconds.) """ return self._client.call_method('SampleService.create_data_link', [params], self._service_ver, context) diff --git a/lib/SampleService/SampleServiceImpl.py b/lib/SampleService/SampleServiceImpl.py index 00c054ee..c4e9b9fb 100644 --- a/lib/SampleService/SampleServiceImpl.py +++ b/lib/SampleService/SampleServiceImpl.py @@ -52,7 +52,7 @@ class SampleService: ######################################### noqa VERSION = "0.1.0-alpha14" GIT_URL = "https://github.com/mrcreosote/sample_service.git" - GIT_COMMIT_HASH = "6a9a9f940e9da95ef926485b7a94555657ceb94e" + GIT_COMMIT_HASH = "645eb0a62d2435761d74ab348adc0ac51eb69ef7" #BEGIN_CLASS_HEADER #END_CLASS_HEADER @@ -387,8 +387,35 @@ def create_data_link(self, ctx, params): (A boolean value, 0 for false, 1 for true.), parameter "as_admin" of type "boolean" (A boolean value, 0 for false, 1 for true.), parameter "as_user" of type "user" (A user's username.) + :returns: instance of type "CreateDataLinkResults" (create_data_link + results. new_link - the new link.) -> structure: parameter + "new_link" of type "DataLink" (A data link from a KBase workspace + object to a sample. upa - the workspace UPA of the linked object. + dataid - the dataid of the linked data, if any, within the object. + If omitted the entire object is linked to the sample. id - the + sample id. version - the sample version. node - the sample node. + createdby - the user that created the link. created - the time the + link was created. expiredby - the user that expired the link, if + any. expired - the time the link was expired, if at all.) -> + structure: parameter "upa" of type "ws_upa" (A KBase Workspace + service Unique Permanent Address (UPA). E.g. 5/6/7 where 5 is the + workspace ID, 6 the object ID, and 7 the object version.), + parameter "dataid" of type "data_id" (An id for a unit of data + within a KBase Workspace object. A single object may contain many + data units. A dataid is expected to be unique within a single + object. Must be less than 255 characters.), parameter "id" of type + "sample_id" (A Sample ID. Must be globally unique. Always assigned + by the Sample service.), parameter "version" of type "version" + (The version of a sample. Always > 0.), parameter "node" of type + "node_id" (A SampleNode ID. Must be unique within a Sample and be + less than 255 characters.), parameter "createdby" of type "user" + (A user's username.), parameter "created" of type "timestamp" (A + timestamp in epoch milliseconds.), parameter "expiredby" of type + "user" (A user's username.), parameter "expired" of type + "timestamp" (A timestamp in epoch milliseconds.) """ # ctx is the context object + # return variables are: results #BEGIN create_data_link duid, sna, update = _create_data_link_params(params) as_admin, user = _get_admin_request_from_object(params, 'as_admin', 'as_user') @@ -396,14 +423,22 @@ def create_data_link(self, ctx, params): self._user_lookup, ctx[_CTX_TOKEN], _AdminPermission.FULL, # pretty annoying to test ctx.log_info is working, do it manually 'create_data_link', ctx.log_info, as_user=user, skip_check=not as_admin) - self._samples.create_data_link( + link = self._samples.create_data_link( user if user else _UserID(ctx[_CTX_USER]), duid, sna, update, as_admin=as_admin) + results = {'new_link': _links_to_dicts([link])[0]} #END create_data_link + # At some point might do deeper type checking... + if not isinstance(results, dict): + raise ValueError('Method create_data_link return value ' + + 'results is not type dict as required.') + # return the results + return [results] + def expire_data_link(self, ctx, params): """ Expire a link from a KBase Workspace object. diff --git a/test/SampleService_test.py b/test/SampleService_test.py index 2d9f4038..2d023ece 100644 --- a/test/SampleService_test.py +++ b/test/SampleService_test.py @@ -1572,7 +1572,7 @@ def _create_sample(url, token, sample, expected_version): return ret.json()['result'][0]['id'] -def _create_link(url, token, params, print_resp=False): +def _create_link(url, token, expected_user, params, print_resp=False): ret = requests.post(url, headers=get_authorized_headers(token), json={ 'method': 'SampleService.create_data_link', 'version': '1.1', @@ -1582,6 +1582,20 @@ def _create_link(url, token, params, print_resp=False): if print_resp: print(ret.text) assert ret.ok is True + link = ret.json()['result'][0]['new_link'] + created = link['created'] + assert_ms_epoch_close_to_now(created) + del link['created'] + assert link == { + 'id': params['id'], + 'version': params['version'], + 'node': params['node'], + 'upa': params['upa'], + 'dataid': params.get('dataid'), + 'createdby': expected_user, + 'expiredby': None, + 'expired': None + } def test_create_links_and_get_links_from_sample_basic(sample_port, workspace): @@ -1638,13 +1652,14 @@ def test_create_links_and_get_links_from_sample_basic(sample_port, workspace): ) # create links + # as_user should be ignored unless as_admin is true + _create_link(url, TOKEN3, USER3, + {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/2/2', 'as_user': USER1}) _create_link( - url, TOKEN3, {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/2/2', 'as_user': USER1}) - _create_link( - url, TOKEN3, + url, TOKEN3, USER3, {'id': id1, 'version': 1, 'node': 'root', 'upa': '1/1/1', 'dataid': 'column1'}) _create_link( - url, TOKEN4, + url, TOKEN4, USER4, {'id': id2, 'version': 1, 'node': 'foo2', 'upa': '1/2/1', 'dataid': 'column2'}) # get links from sample 1 @@ -1766,33 +1781,23 @@ def test_update_and_get_links_from_sample(sample_port, workspace): _replace_acls(url, id1, TOKEN3, {'admin': [USER4]}) # create links - ret = requests.post(url, headers=get_authorized_headers(TOKEN3), json={ - 'method': 'SampleService.create_data_link', - 'version': '1.1', - 'id': '42', - 'params': [{'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/1/1', 'dataid': 'yay'}] - }) - # print(ret.text) - assert ret.ok is True + _create_link(url, TOKEN3, USER3, + {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/1/1', 'dataid': 'yay'}) oldlinkactive = datetime.datetime.now() time.sleep(1) # update link node - ret = requests.post(url, headers=get_authorized_headers(TOKEN4), json={ - 'method': 'SampleService.create_data_link', - 'version': '1.1', - 'id': '42', - 'params': [ + _create_link( + url, + TOKEN4, + USER4, {'id': id1, 'version': 1, 'node': 'root', 'upa': '1/1/1', 'dataid': 'yay', - 'update': 1}] - }) - # print(ret.text) - assert ret.ok is True + 'update': 1}) # get current link ret = requests.post(url, headers=get_authorized_headers(TOKEN3), json={ @@ -1887,6 +1892,7 @@ def test_create_data_link_as_admin(sample_port, workspace): _create_link( url, TOKEN2, + USER2, {'id': id1, 'version': 1, 'node': 'root', @@ -1896,6 +1902,7 @@ def test_create_data_link_as_admin(sample_port, workspace): _create_link( url, TOKEN2, + USER4, {'id': id1, 'version': 1, 'node': 'foo', @@ -1986,11 +1993,11 @@ def test_get_links_from_sample_exclude_workspaces(sample_port, workspace): _replace_acls(url, id_, TOKEN3, {'admin': [USER4]}) # create links - _create_link(url, TOKEN3, {'id': id_, 'version': 1, 'node': 'foo', 'upa': '1/1/1'}) - _create_link(url, TOKEN4, {'id': id_, 'version': 1, 'node': 'foo', 'upa': '2/1/1'}) - _create_link( - url, TOKEN4, {'id': id_, 'version': 1, 'node': 'foo', 'upa': '3/1/1', 'dataid': 'whee'}) - _create_link(url, TOKEN4, {'id': id_, 'version': 1, 'node': 'foo', 'upa': '4/1/1'}) + _create_link(url, TOKEN3, USER3, {'id': id_, 'version': 1, 'node': 'foo', 'upa': '1/1/1'}) + _create_link(url, TOKEN4, USER4, {'id': id_, 'version': 1, 'node': 'foo', 'upa': '2/1/1'}) + _create_link(url, TOKEN4, USER4, + {'id': id_, 'version': 1, 'node': 'foo', 'upa': '3/1/1', 'dataid': 'whee'}) + _create_link(url, TOKEN4, USER4, {'id': id_, 'version': 1, 'node': 'foo', 'upa': '4/1/1'}) # check correct links are returned ret = requests.post(url, headers=get_authorized_headers(TOKEN3), json={ @@ -2063,7 +2070,7 @@ def test_get_links_from_sample_as_admin(sample_port, workspace): id_ = _create_generic_sample(url, TOKEN4) # create links - _create_link(url, TOKEN4, {'id': id_, 'version': 1, 'node': 'foo', 'upa': '1/1/1'}) + _create_link(url, TOKEN4, USER4, {'id': id_, 'version': 1, 'node': 'foo', 'upa': '1/1/1'}) # check correct links are returned, user 3 has read admin perms, but not full ret = requests.post(url, headers=get_authorized_headers(TOKEN3), json={ @@ -2179,14 +2186,8 @@ def test_create_link_fail_link_exists(sample_port, workspace): id_ = _create_generic_sample(url, TOKEN3) - ret = requests.post(url, headers=get_authorized_headers(TOKEN3), json={ - 'method': 'SampleService.create_data_link', - 'version': '1.1', - 'id': '42', - 'params': [{'id': id_, 'version': 1, 'node': 'foo', 'upa': '1/1/1', 'dataid': 'yay'}] - }) - # print(ret.text) - assert ret.ok is True + _create_link(url, TOKEN3, USER3, + {'id': id_, 'version': 1, 'node': 'foo', 'upa': '1/1/1', 'dataid': 'yay'}) _create_link_fail( sample_port, TOKEN3, @@ -2289,10 +2290,10 @@ def _expire_data_link(sample_port, workspace, dataid): _replace_acls(url, id1, TOKEN3, {'admin': [USER4]}) # create links - _create_link( - url, TOKEN3, {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/1/1', 'dataid': dataid}) - _create_link( - url, TOKEN3, {'id': id1, 'version': 1, 'node': 'bar', 'upa': '1/1/1', 'dataid': 'fake'}) + _create_link(url, TOKEN3, USER3, + {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/1/1', 'dataid': dataid}) + _create_link(url, TOKEN3, USER3, + {'id': id1, 'version': 1, 'node': 'bar', 'upa': '1/1/1', 'dataid': 'fake'}) time.sleep(1) # need to be able to set a resonable effective time to fetch links @@ -2390,8 +2391,8 @@ def _expire_data_link_as_admin(sample_port, workspace, user, expected_user): ) # create links - _create_link( - url, TOKEN3, {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/1/1', 'dataid': 'duidy'}) + _create_link(url, TOKEN3, USER3, + {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/1/1', 'dataid': 'duidy'}) time.sleep(1) # need to be able to set a resonable effective time to fetch links @@ -2461,8 +2462,8 @@ def test_expire_data_link_fail(sample_port, workspace): ) # create links - _create_link( - url, TOKEN3, {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/1/1', 'dataid': 'yay'}) + _create_link(url, TOKEN3, USER3, + {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/1/1', 'dataid': 'yay'}) _expire_data_link_fail( sample_port, TOKEN3, {}, 'Sample service error code 30000 Missing input parameter: upa') @@ -2581,12 +2582,12 @@ def test_get_links_from_data(sample_port, workspace): ) # create links - _create_link(url, TOKEN3, {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/2/2'}) + _create_link(url, TOKEN3, USER3, {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/2/2'}) _create_link( - url, TOKEN4, + url, TOKEN4, USER4, {'id': id2, 'version': 1, 'node': 'root2', 'upa': '1/1/1', 'dataid': 'column1'}) _create_link( - url, TOKEN4, + url, TOKEN4, USER4, {'id': id2, 'version': 2, 'node': 'foo3', 'upa': '1/2/2', 'dataid': 'column2'}) # get links from object 1/2/2 @@ -2704,14 +2705,14 @@ def test_get_links_from_data_expired(sample_port, workspace): _replace_acls(url, id1, TOKEN3, {'admin': [USER4]}) # create links - _create_link( - url, TOKEN3, {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/1/1', 'dataid': 'yay'}) + _create_link(url, TOKEN3, USER3, + {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/1/1', 'dataid': 'yay'}) oldlinkactive = datetime.datetime.now() time.sleep(1) # update link node - _create_link(url, TOKEN4, { + _create_link(url, TOKEN4, USER4, { 'id': id1, 'version': 1, 'node': 'root', @@ -2809,7 +2810,7 @@ def test_get_links_from_data_as_admin(sample_port, workspace): ) # create links - _create_link(url, TOKEN4, {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/1/1'}) + _create_link(url, TOKEN4, USER4, {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/1/1'}) # get links from object, user 3 has admin read perms ret = requests.post(url, headers=get_authorized_headers(TOKEN3), json={ @@ -2947,9 +2948,9 @@ def test_get_sample_via_data(sample_port, workspace): ) # create links - _create_link(url, TOKEN3, {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/1/1'}) + _create_link(url, TOKEN3, USER3, {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/1/1'}) _create_link( - url, TOKEN3, + url, TOKEN3, USER3, {'id': id2, 'version': 2, 'node': 'root3', 'upa': '1/1/1', 'dataid': 'column1'}) # get first sample via link from object 1/1/1 using a token that has no access @@ -3020,7 +3021,7 @@ def test_get_sample_via_data(sample_port, workspace): assert res == expected -def test_get_sample_via_from_data_expired(sample_port, workspace): +def test_get_sample_via_data_expired(sample_port, workspace): url = f'http://localhost:{sample_port}' wsurl = f'http://localhost:{workspace.port}' wscli = Workspace(wsurl, token=TOKEN3) @@ -3055,11 +3056,11 @@ def test_get_sample_via_from_data_expired(sample_port, workspace): ) # create links - _create_link( - url, TOKEN3, {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/1/1', 'dataid': 'yay'}) + _create_link(url, TOKEN3, USER3, + {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/1/1', 'dataid': 'yay'}) # update link node - _create_link(url, TOKEN3, { + _create_link(url, TOKEN3, USER3, { 'id': id2, 'version': 1, 'node': 'root2', @@ -3162,8 +3163,8 @@ def test_get_sample_via_data_fail(sample_port, workspace): ) # create links - _create_link( - url, TOKEN3, {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/1/1', 'dataid': 'yay'}) + _create_link(url, TOKEN3, USER3, + {'id': id1, 'version': 1, 'node': 'foo', 'upa': '1/1/1', 'dataid': 'yay'}) _get_sample_via_data_fail( sample_port, TOKEN3, {},