diff --git a/SampleService.html b/SampleService.html index 21fafd00..cd53a0d9 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 link ID. Must be globally unique. Always assigned by the Sample service.
*Typically only of use to service admins.
*/
typedefstringlink_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;

/*
*A metadata value, represented by a mapping of value keys to primitive values. An example for
*a location metadata key might be:
*{
*"name": "Castle Geyser",
*"lat": 44.463816,
*"long": -110.836471
*}
*"primitive values" means an int, float, string, or equivalent typedefs. Including any
*collection types is an error.
*/
typedefmapping<metadata_value_key,UnspecifiedObject>metadata_value;

/*
*Metadata attached to a sample.
*/
typedefmapping<metadata_key,metadata_value>metadata;

/*
*Information about a metadata key as it appeared at the data source.
*The source key and value represents the original state of the metadata before it was
*tranformed for ingestion by the sample service.
*
*key - the metadata key.
*skey - the key as it appeared at the data source.
*svalue - the value as it appeared at the data source.
*/
typedefstructure{
metadata_keykey;
metadata_keyskey;
metadata_valuesvalue;
}
SourceMetadata;

/*
*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.
*source_meta - the pre-transformation keys and values of the controlled metadata at the
*data source for controlled metadata keys. In some cases the source metadata
*may be transformed prior to ingestion by the Sample Service; the contents of this
*data structure allows for reconstructing the original representation. The metadata
*here is not validated other than basic size checks and is provided on an
*informational basis only. The metadata keys in the SourceMetadata data structure
*must be a subset of the meta_controlled mapping keys.
*meta_user - unrestricted metadata.
*/
typedefstructure{
node_idid;
node_idparent;
samplenode_typetype;
metadatameta_controlled;
list<SourceMetadata>source_meta;
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.
*public_read - whether any user can read the sample, regardless of permissions.
*/
typedefstructure{
userowner;
list<user>admin;
list<user>write;
list<user>read;
booleanpublic_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)authenticationoptional;

/*
*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)authenticationoptional;

/*
*update_sample_acls parameters.
*
*id - the ID of the sample to modify.
*admin - a list of users that will receive admin privileges. Default none.
*write - a list of users that will receive write privileges. Default none.
*read - a list of users that will receive read privileges. Default none.
*remove - a list of users that will have all privileges removed. Default none.
*public_read - an integer that determines whether the sample will be set to publicly
*readable:
*> 0: public read.
*0: No change (the default).
*< 0: private.
*as_admin - update the sample acls regardless of sample ACL contents as long as the user has
*full service administration permissions.
*/
typedefstructure{
sample_idid;
list<user>admin;
list<user>write;
list<user>read;
list<user>remove;
intpublic_read;
booleanas_admin;
}
UpdateSampleACLsParams;

/*
*Update a sample's ACLs.
*/
funcdefupdate_sample_acls(UpdateSampleACLsParamsparams)returns()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 sample ACL contents as long as the user
*has full service 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{
link_idlinkid;
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)authenticationoptional;

/*
*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)authenticationoptional;

/*
*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)authenticationoptional;

/*
*get_data_link parameters.
*
*linkid - the link ID.
*/
typedefstructure{
link_idlinkid;
}
GetDataLinkParams;

/*
*Get a link, expired or not, by its ID. This method requires read administration privileges
*for the service.
*/
funcdefget_data_link(GetDataLinkParamsparams)returns(DataLinklink)authenticationrequired;
};

Function Index

create_data_link
create_sample
expire_data_link
get_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
update_sample_acls

Type Index

boolean
CreateDataLinkParams
CreateDataLinkResults
CreateSampleParams
data_id
DataLink
ExpireDataLinkParams
GetDataLinkParams
GetDataLinksFromDataParams
GetDataLinksFromDataResults
GetDataLinksFromSampleParams
GetDataLinksFromSampleResults
GetMetadataKeyStaticMetadataParams
GetMetadataKeyStaticMetadataResults
GetSampleACLsParams
GetSampleParams
GetSampleViaDataParams
link_id
metadata
metadata_key
metadata_value
metadata_value_key
node_id
ReplaceSampleACLsParams
Sample
sample_id
sample_name
SampleACLs
SampleAddress
SampleNode
samplenode_type
SourceMetadata
timestamp
UpdateSampleACLsParams
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 link ID. Must be globally unique. Always assigned by the Sample service.
*Typically only of use to service admins.
*/
typedefstringlink_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;

/*
*A metadata value, represented by a mapping of value keys to primitive values. An example for
*a location metadata key might be:
*{
*"name": "Castle Geyser",
*"lat": 44.463816,
*"long": -110.836471
*}
*"primitive values" means an int, float, string, or equivalent typedefs. Including any
*collection types is an error.
*/
typedefmapping<metadata_value_key,UnspecifiedObject>metadata_value;

/*
*Metadata attached to a sample.
*/
typedefmapping<metadata_key,metadata_value>metadata;

/*
*Information about a metadata key as it appeared at the data source.
*The source key and value represents the original state of the metadata before it was
*tranformed for ingestion by the sample service.
*
*key - the metadata key.
*skey - the key as it appeared at the data source.
*svalue - the value as it appeared at the data source.
*/
typedefstructure{
metadata_keykey;
metadata_keyskey;
metadata_valuesvalue;
}
SourceMetadata;

/*
*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.
*source_meta - the pre-transformation keys and values of the controlled metadata at the
*data source for controlled metadata keys. In some cases the source metadata
*may be transformed prior to ingestion by the Sample Service; the contents of this
*data structure allows for reconstructing the original representation. The metadata
*here is not validated other than basic size checks and is provided on an
*informational basis only. The metadata keys in the SourceMetadata data structure
*must be a subset of the meta_controlled mapping keys.
*meta_user - unrestricted metadata.
*/
typedefstructure{
node_idid;
node_idparent;
samplenode_typetype;
metadatameta_controlled;
list<SourceMetadata>source_meta;
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.
*public_read - whether any user can read the sample, regardless of permissions.
*/
typedefstructure{
userowner;
list<user>admin;
list<user>write;
list<user>read;
booleanpublic_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)authenticationoptional;

/*
*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)authenticationoptional;

/*
*update_sample_acls parameters.
*
*id - the ID of the sample to modify.
*admin - a list of users that will receive admin privileges. Default none.
*write - a list of users that will receive write privileges. Default none.
*read - a list of users that will receive read privileges. Default none.
*remove - a list of users that will have all privileges removed. Default none.
*public_read - an integer that determines whether the sample will be set to publicly
*readable:
*> 0: public read.
*0: No change (the default).
*< 0: private.
*at_least - false, the default, indicates that the users should get the exact permissions
*as specified in the user lists, which may mean a reduction in permissions. If true,
*users that already exist in the sample ACLs will not have their permissions reduced
*as part of the ACL update unless they are in the remove list. E.g. if a user has
*write permissions and read permissions are specified in the update, no changes will
*be made to the user's permission.
*as_admin - update the sample acls regardless of sample ACL contents as long as the user has
*full service administration permissions.
*/
typedefstructure{
sample_idid;
list<user>admin;
list<user>write;
list<user>read;
list<user>remove;
intpublic_read;
booleanat_least;
booleanas_admin;
}
UpdateSampleACLsParams;

/*
*Update a sample's ACLs.
*/
funcdefupdate_sample_acls(UpdateSampleACLsParamsparams)returns()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 sample ACL contents as long as the user
*has full service 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{
link_idlinkid;
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)authenticationoptional;

/*
*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)authenticationoptional;

/*
*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)authenticationoptional;

/*
*get_data_link parameters.
*
*linkid - the link ID.
*/
typedefstructure{
link_idlinkid;
}
GetDataLinkParams;

/*
*Get a link, expired or not, by its ID. This method requires read administration privileges
*for the service.
*/
funcdefget_data_link(GetDataLinkParamsparams)returns(DataLinklink)authenticationrequired;
};

Function Index

create_data_link
create_sample
expire_data_link
get_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
update_sample_acls

Type Index

boolean
CreateDataLinkParams
CreateDataLinkResults
CreateSampleParams
data_id
DataLink
ExpireDataLinkParams
GetDataLinkParams
GetDataLinksFromDataParams
GetDataLinksFromDataResults
GetDataLinksFromSampleParams
GetDataLinksFromSampleResults
GetMetadataKeyStaticMetadataParams
GetMetadataKeyStaticMetadataResults
GetSampleACLsParams
GetSampleParams
GetSampleViaDataParams
link_id
metadata
metadata_key
metadata_value
metadata_value_key
node_id
ReplaceSampleACLsParams
Sample
sample_id
sample_name
SampleACLs
SampleAddress
SampleNode
samplenode_type
SourceMetadata
timestamp
UpdateSampleACLsParams
user
version
ws_upa
\ No newline at end of file diff --git a/SampleService.spec b/SampleService.spec index b5a58c8e..b5146fe1 100644 --- a/SampleService.spec +++ b/SampleService.spec @@ -226,6 +226,12 @@ module SampleService { > 0: public read. 0: No change (the default). < 0: private. + at_least - false, the default, indicates that the users should get the exact permissions + as specified in the user lists, which may mean a reduction in permissions. If true, + users that already exist in the sample ACLs will not have their permissions reduced + as part of the ACL update unless they are in the remove list. E.g. if a user has + write permissions and read permissions are specified in the update, no changes will + be made to the user's permission. as_admin - update the sample acls regardless of sample ACL contents as long as the user has full service administration permissions. */ @@ -236,6 +242,7 @@ module SampleService { list read; list remove; int public_read; + boolean at_least; boolean as_admin; } UpdateSampleACLsParams; diff --git a/lib/SampleService/SampleServiceClient.py b/lib/SampleService/SampleServiceClient.py index 68d0bef3..5e4cd982 100644 --- a/lib/SampleService/SampleServiceClient.py +++ b/lib/SampleService/SampleServiceClient.py @@ -280,7 +280,14 @@ def update_sample_acls(self, params, context=None): of users that will have all privileges removed. Default none. public_read - an integer that determines whether the sample will be set to publicly readable: > 0: public read. 0: No change (the - default). < 0: private. as_admin - update the sample acls + default). < 0: private. at_least - false, the default, indicates + that the users should get the exact permissions as specified in + the user lists, which may mean a reduction in permissions. If + true, users that already exist in the sample ACLs will not have + their permissions reduced as part of the ACL update unless they + are in the remove list. E.g. if a user has write permissions and + read permissions are specified in the update, no changes will be + made to the user's permission. as_admin - update the sample acls regardless of sample ACL contents as long as the user has full service administration permissions.) -> structure: parameter "id" of type "sample_id" (A Sample ID. Must be globally unique. Always @@ -289,8 +296,9 @@ def update_sample_acls(self, params, context=None): type "user" (A user's username.), parameter "read" of list of type "user" (A user's username.), parameter "remove" of list of type "user" (A user's username.), parameter "public_read" of Long, - parameter "as_admin" of type "boolean" (A boolean value, 0 for - false, 1 for true.) + parameter "at_least" of type "boolean" (A boolean value, 0 for + false, 1 for true.), parameter "as_admin" of type "boolean" (A + boolean value, 0 for false, 1 for true.) """ return self._client.call_method('SampleService.update_sample_acls', [params], self._service_ver, context) diff --git a/lib/SampleService/SampleServiceImpl.py b/lib/SampleService/SampleServiceImpl.py index 1871419b..adab94d1 100644 --- a/lib/SampleService/SampleServiceImpl.py +++ b/lib/SampleService/SampleServiceImpl.py @@ -54,7 +54,7 @@ class SampleService: ######################################### noqa VERSION = "0.1.0-alpha21" GIT_URL = "https://github.com/mrcreosote/sample_service.git" - GIT_COMMIT_HASH = "b6daa022f7eb7eb7a48156022619b21febf103f4" + GIT_COMMIT_HASH = "67b70bb587fbf1212a06c716e2e44b0d161cd4c7" #BEGIN_CLASS_HEADER #END_CLASS_HEADER @@ -362,7 +362,14 @@ def update_sample_acls(self, ctx, params): of users that will have all privileges removed. Default none. public_read - an integer that determines whether the sample will be set to publicly readable: > 0: public read. 0: No change (the - default). < 0: private. as_admin - update the sample acls + default). < 0: private. at_least - false, the default, indicates + that the users should get the exact permissions as specified in + the user lists, which may mean a reduction in permissions. If + true, users that already exist in the sample ACLs will not have + their permissions reduced as part of the ACL update unless they + are in the remove list. E.g. if a user has write permissions and + read permissions are specified in the update, no changes will be + made to the user's permission. as_admin - update the sample acls regardless of sample ACL contents as long as the user has full service administration permissions.) -> structure: parameter "id" of type "sample_id" (A Sample ID. Must be globally unique. Always @@ -371,8 +378,9 @@ def update_sample_acls(self, ctx, params): type "user" (A user's username.), parameter "read" of list of type "user" (A user's username.), parameter "remove" of list of type "user" (A user's username.), parameter "public_read" of Long, - parameter "as_admin" of type "boolean" (A boolean value, 0 for - false, 1 for true.) + parameter "at_least" of type "boolean" (A boolean value, 0 for + false, 1 for true.), parameter "as_admin" of type "boolean" (A + boolean value, 0 for false, 1 for true.) """ # ctx is the context object #BEGIN update_sample_acls diff --git a/test/SampleService_test.py b/test/SampleService_test.py index 17e293e3..b3fa5f7a 100644 --- a/test/SampleService_test.py +++ b/test/SampleService_test.py @@ -1653,7 +1653,7 @@ def _update_acls_tst(sample_port, kafka, token, as_admin): 'admin': [USER2], 'write': [USER_NO_TOKEN1, USER_NO_TOKEN2, USER3], 'read': [USER_NO_TOKEN3, USER4], - 'public_read': 1 + 'public_read': 0 }) _update_acls(url, token, { @@ -1663,7 +1663,7 @@ def _update_acls_tst(sample_port, kafka, token, as_admin): 'read': [USER_NO_TOKEN2], 'remove': [USER3], 'public_read': 390, - 'as_admin': 1 if as_admin else 0 + 'as_admin': 1 if as_admin else 0, }) _assert_acl_contents(url, id_, TOKEN1, { @@ -1683,6 +1683,53 @@ def _update_acls_tst(sample_port, kafka, token, as_admin): ]) +def test_update_acls_with_at_least(sample_port, kafka): + _update_acls_tst_with_at_least(sample_port, kafka, TOKEN1, False) # owner + _update_acls_tst_with_at_least(sample_port, kafka, TOKEN2, False) # admin + _update_acls_tst_with_at_least(sample_port, kafka, TOKEN5, True) # as_admin = True + + +def _update_acls_tst_with_at_least(sample_port, kafka, token, as_admin): + _clear_kafka_messages(kafka) + url = f'http://localhost:{sample_port}' + + id_ = _create_generic_sample(url, TOKEN1) + + _replace_acls(url, id_, TOKEN1, { + 'admin': [USER2], + 'write': [USER_NO_TOKEN1, USER_NO_TOKEN2, USER3], + 'read': [USER_NO_TOKEN3, USER4], + 'public_read': 0 + }) + + _update_acls(url, token, { + 'id': str(id_), + 'admin': [USER4], + 'write': [USER2, USER_NO_TOKEN3], + 'read': [USER_NO_TOKEN2, USER5], + 'remove': [USER3], + 'public_read': 390, + 'as_admin': 1 if as_admin else 0, + 'at_least': 1, + }) + + _assert_acl_contents(url, id_, TOKEN1, { + 'owner': USER1, + 'admin': [USER2, USER4], + 'write': [USER_NO_TOKEN1, USER_NO_TOKEN2, USER_NO_TOKEN3], + 'read': [USER5], + 'public_read': 1 + }, print_resp=True) + + _check_kafka_messages( + kafka, + [ + {'event_type': 'NEW_SAMPLE', 'sample_id': id_, 'sample_ver': 1}, + {'event_type': 'ACL_CHANGE', 'sample_id': id_}, + {'event_type': 'ACL_CHANGE', 'sample_id': id_}, + ]) + + def test_update_acls_fail_no_id(sample_port): url = f'http://localhost:{sample_port}'