See Scenarios: File / Folder API for driving use cases for this design. An entity is an object that represents either a file or a folder. The attributes of file entities and folder entities are similar to the attributes of files and folders on a hard drive:
The following class diagram (figure 1) is not meant to be exhaustive, but rather show the basic relationships of entities as related to files and folders.
We have updated the object model to incorporate feed back and consider how Competition objects (might be renamed to Evaluation objects) work with wiki markdown.
V2 Changes:
V3 Changes:
Updated Object model:
Figure 1 - Entity class diagram.
Note: All relative URLs in this document are assumed to point to be: https://repo-prod.sagebase.org/repo/v1. The full URL will be provided whenever this is not the case.
operation | Required permissions |
---|---|
POST | To create an entity, the caller must have the CREATE permission on the Entity's parent Entity. When a 'dataFileHandleId' is set for Entity create, the caller must also be the creator of the corresponding FileHandle |
PUT | To update an entity, the caller must have the EDIT permission on the Entity. When 'dataFileHandleId' is changed, the caller must also be the creator of the corresponding FileHandle. If the caller has EDIT permission they can set the 'dataFileHandleId' to be null without any additional permissions. If an Entity update does not change the 'dataFileHandleId' no special permissions are required. |
GET /entity | A caller can GET an entity if they have the READ permission on the Entity. Note: If an Entity has a valid 'dataFileHandleId' and the the caller has READ permission on Entity the valid 'dataFileHandleId' will be returned. The 'dataFileHandleId' will be returned, even if the caller does not have download permission on that entity. This means a caller can determine the existence of a file even if they lack the permission to download it. |
GET /entity/{entityId}/file | The ability for a caller to download a file associated with an Entity is based on several factors including, READ permission on the Entity, signing the terms-of-use (ToU), and any special data restrictions applied to sensitive data. A caller must meet all access requirements in order to download any file associated with an Entity. For more information on data access see: Authentication and Authorization API |
GET /entity/{entityId}/filehandles | To access the FileHandle associated with the 'dataFileHandleId', the caller must meet all of the download requirements of the actual data file (same as GET /entity/file). |
Note: Only the new FileHandle API's for FileEntites are covered in this section. See following for the full Entity API: Repository Service API#Create/Update/DeleteExamples
URL | HTTP type | Description |
---|---|---|
/entity/{enityId}/file | GET | Attempt to download the raw file currently associated with the current version of the Entity. Note: This call will result in a HTTP temporary redirect (307), to the real file URL if the caller meets all of the download requirements. |
/entity/{enityId}/filepreview | GET | Attempt to download the preview of the file currently associated with the current version of the Entity. Note: This call will result in a HTTP temporary redirect (307), to the real file URL if the caller meets all of the download requirements. |
/entity/{enityId}/filehandles | GET | Get the FileHandles of the file currently associated with the current version of the Entity. If a preview exists for the file then the handle of the preview and the file will be returned with this call. |
/entity/{entityId}/version/{versionNumber}/file | GET | Attempt to download the raw file of an entity for a given version number of the entity. Note: This call will result in a HTTP temporary redirect (307), to the real file URL if the caller meets all of the download requirements. |
/entity/{entityId}/version/{versionNumber}/filepreview | GET | Attempt to download preview of the file of an entity for a given version number of the entity. Note: This call will result in a HTTP temporary redirect (307), to the real file URL if the caller meets all of the download requirements. |
/entity/{entityId}/version/{versionNumber}/filehandles | GET | Get the FileHandles of the file associated with the given version number of the entity. If a preview exists for the file then the handle of the preview and the file will be returned with this call. |
See also: FileHandle API