REST API for getting, analyzing, and updating the required rights of a document.

Description

This extension provides a REST API for getting, analyzing, and updating the required rights of a document. It is used by the modal that is provided by the Required Rights UI. This extension provides two endpoints, one for getting the required rights of a document including a full analysis of the required rights the document might need, and one for setting the required rights. While the latter is also possible with the existing APIs, this API simplifies updating required rights a lot by abstracting away from the concrete storage of the enforced required rights in XObjects.

/wikis/{wikiName}/spaces/{spaceName: .+}/pages/{pageName}/requiredRights

• HTTP Method: GET
  • Media Types:
    • application/json
  • Description:
    • This endpoint returns an object with data about the required rights of a page, the primary intention is to provide all data for users to decide which rights to enforce:
      • analysisResults: A list of objects representing the required rights analysis results, each object has:
        • entityReference: The entity reference without locale. (string)
        • locale: The locale. (string)
        • summaryMessageHTML: A summary message in HTML format, describes the object (like the macro, XObject, XObject property type, …) and the required right. (string) 
        • detailedMessageHTML: A detailed message in HTML format, contains for example the full parameters and content of a macro or all properties of an XObject. (string)
        • requiredRights: A list of RequiredRight objects, each object has:
          • right: The right (like script, admin, programming). (string)
          • entityType: The entity type, like DOCUMENT or WIKI, can be null when the right is required on the farm. (string)
          • manualReviewNeeded: Indicates if a manual review of the analysis result is required to determine if the right is actually required. (boolean)
      • currentRights: A list of objects representing the required rights currently configured on a document, each object has:
        • enforce: Indicates if required rights are enforced. (boolean)
        • rights: A list of objects representing the current rights, each object has:
          • right: The right (like script, admin, programming). (string) 
          • scope: The scope of the right (like DOCUMENT, WIKI, or null for farm). (string)
      • availableRights: A list of objects representing rights that could be configured on a document, each object has:
        • right: The right, or empty string for no right. (string) 
        • scope: The scope of the right, can be null for farm. (string)
        • displayName: The (translated) display name of the right. (string)
        • hasRight: Indicates if the current user has the right. (boolean)
        • definitelyRequiredRight: Indicates if the right is definitely required according to the analysis results. (boolean) 
        • maybeRequiredRight: Indicates if the right might be required according to the analysis results. (boolean) 
  • Status codes:
    • 200 if the request was successful
    • 404 if the page doesn't exist
    • 401 if the user isn't authorized
• HTTP Method: PUT
  • Accepted Media types:
    • application/json
  • Media Types:
    • application/json
  • Description:
    • Both the request and the response use the same format as the currentRights in the GET method above. The response contains the rights after saving. The rights are only saved if they are actually changed. The listed rights are only saved when enforcing is enabled. For the saving to succeed, the user must have edit right as well as all enforced required rights.
  • Status codes:
    • 200 if the request was successful
    • 404 if the page doesn't exist (this call doesn't allow creating the page)
    • 401 if the user isn't authorized

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-security-requiredrights-rest 18.4.0):

• org.xwiki.platform:xwiki-platform-rest-server 18.4.0
• org.xwiki.platform:xwiki-platform-security-requiredrights-default 18.4.0
• org.xwiki.rendering:xwiki-rendering-api 18.4.0