Wiki API (Alpha)
- John Hill
- Chris Bare (Unlicensed)
Note: This feature is currently in Alpha and all functionality is not currently support.
Wiki REST
Wiki pages are currently not stand-alone objects, rather they are a component of another object such as an Entity, Competition or Evaluation. Therefore, access to a wiki page is gated by its owner object
Note: WikiPages can be nested to created a hierarchy of sub-pages. However, there can only be one root WikiPage per owner object, and all sub-pages are considered to be owned by the same object.
WikiPage
| field | Description |
|---|---|
| id | The unique immutable identifier assigned to a wiki page when it is first created. This is used |
| etag | Used for concurrency management. Each time a WikiPage changes the etag will change. |
| createdBy | The ID of the user that created the WikiPage |
| createdOn | The date when the WikiPage was first created. |
| modifiedBy | The ID of the user that last modified the wiki page. |
| modifiedOn | The data when the WikiPage was last modified. |
| title | The main tile of the wiki page. |
| markdown | The main body of the wiki page is represented as markdown. |
| attachmentFileHandleIds | The list of FileHandleIds that represent that this WikiPage's attachment files. |
| parentWikiId | Sub-WikiPages are created by setting this to the ID of a parent WikiPage (null for root). Note: This is not the same as the owner of the WikiPage. |
WikiHeader
| field | Description |
|---|---|
| id | The id of the wiki page. |
| title | The title of the wiki page. |
| parentWikiId | The ID of the parent wiki (null for root) |
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.
Permission
The permissions required to perform any wiki related operation are tied to the permission of the owner object and the HTTP type. For example, if you have CREATE permission on an Entity, then you can create a Wiki page for that entity. Similarly, if you can EDIT an entity, then you can also edit any wiki page associated with the entity. This means all REST call for wiki pages involve the owner object.
| HTTP type | Required Permission |
|---|---|
| POST | The caller must have the CREATE permission on the owner object to perform this action. |
| GET | The caller must have the READ permission on the owner object to perform this action. |
| PUT | The caller must have the EDIT permission on the owner object to perform this action. |
| DELETE | The caller must have DELETE permission on the owner object to perform this action. |
CRUD REST
| URL | HTTP type | Description |
|---|---|---|
| /{ownertObjectType}/{ownerObjectId}/wiki | POST | Used to create a new wiki page and assign it to an owner object. |
| /{ownertObjectType}/{ownerObjectId}/wikiheadertree | GET | Get entire wiki tree as a list of WikiHeaders. The list is ordered first by parentWikiId and then by title. This can be used to build a tree representation of wiki hierarchy for a given owner object. |
| /{ownertObjectType}/{ownerObjectId}/wiki | GET | Get the root wiki page associated with an object. |
| /{ownertObjectType}/{ownerObjectId}/wiki/{wikiId} | GET | Get a wiki page by its ID. |
| /{ownertObjectType}/{ownerObjectId}/wiki/{wikiId} | PUT | Used to update a wiki. |
| /{ownertObjectType}/{ownerObjectId}/wiki/{wikiId} | DELETE | Used to delete a wiki page. |
Attachments
Each wiki page has its own list of file attachments represented as FileHandleIds. For more information on FileHandles see: FileHandle API.
| URL | HTTP type | Description |
|---|---|---|
| /{ownertObjectType}/{ownerObjectId}/wiki/{wikiId}/attachment?fileName={attachmentFileName} | GET | Attempt to download the raw file attachment using the name of the attachment file instead of the FileHandleId. Note: This call will result in a HTTP temporary redirect (307), to the real file URL if the caller is authorized to READ the owner object. |
| /{ownertObjectType}/{ownerObjectId}/wiki/{wikiId}/attachmentpreview?fileName={attachmentFileName} | GET | Attempt to download the preview file attachment using the name of the attachment file instead of the FileHandleId. Note: This call will result in a HTTP temporary redirect (307), to the real file URL if the caller is authorized to READ the owner object. |
| /{ownertObjectType}/{ownerObjectId}/wiki/{wikiId}/attachmenthandles | GET | Get the FileHandles for all attachments of the given WikiPage. The resulting list will also include any PreviewFileHandles. |
Planned Future API (not currently implemented)
| URL | HTTP type | Description |
|---|---|---|
| /{ownertObjectType}/{ownerObjectId}/wiki | GET | Get the root WikiPage for an owner object. |
| https://file-prod.sagebase.org/file/v1/{ownertObjectType}/{ownerObjectId}/wiki/{wikiId}/attachment | POST (HTTP Multipart) | Add an attachment file to a wiki using HTTP mutlipart POST. Notice, the host for this call is a special file dedicated server. |
| /{ownertObjectType}/{ownerObjectId}/wiki/{wikiId}/attachment/{fileHandleId} | GET | Attempt to download the raw file attachment. Note: This call will result in a HTTP temporary redirect (307), to the real file URL if the caller is authorized to READ the owner object. |
| /{ownertObjectType}/{ownerObjectId}/wiki/{wikiId}/attachmentPreview/{fileHandleId} | GET | Attempt to download the preview file that is automatically generated for all FileHandles. Note: This call will result in a HTTP temporary redirect (307), to the real file URL if the caller is authorized to READ the owner object. |