Merge pull request #11422 from IQSS/11415-app-tou

add API for getting application terms of use

Author: ofahimIQSS

doc/release-notes/11415-app-tou.md

@@ -0,0 +1,3 @@
+### Application Terms of Use Available via API
+
+It's now possible to retrieve the Application Terms of Use (called General Terms of Use in the UI) via API. These are the terms users agree to when creating an account. See [the guides](https://dataverse-guide--11422.org.readthedocs.build/en/11422/api/native-api.html#get-application-terms-of-use-general-terms-of-use), #11415 and #11422.

doc/sphinx-guides/source/admin/metadatacustomization.rst

@@ -312,7 +312,7 @@ FieldType definitions
 |               | permitted, only a subset of HTML   |
 |               | tags will be rendered in the UI.   |
 |               | See the                            |
-|               | :ref:`supported-html-fields`       |
+|               | :ref:`supported-html-tags`         |
 |               | section of the Dataset + File      |
 |               | Management page in the User Guide. |
 +---------------+------------------------------------+

doc/sphinx-guides/source/api/native-api.rst

@@ -5544,6 +5544,28 @@ The fully expanded example above (without environment variables) looks like this
 
   curl "https://demo.dataverse.org/api/info/settings/:DatasetPublishPopupCustomText"
 
+.. _api-get-app-tou:
+
+Get Application Terms of Use (General Terms of Use)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the UI, Application Terms of Use is called "General Terms of Use" and can be seen when you sign up for an account. The terms come from the database setting :ref:`:ApplicationTermsOfUse`. If you have enabled :ref:`i18n` you can pass a two-character language code (e.g. "en") as the ``lang`` parameter.
+
+.. note:: See :ref:`curl-examples-and-environment-variables` if you are unfamiliar with the use of export below.
+
+.. code-block:: bash
+
+  export SERVER_URL=https://demo.dataverse.org
+  export LANG=en
+
+  curl "$SERVER_URL/api/info/applicationTermsOfUse?lang=$LANG"
+
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
+
+  curl "https://demo.dataverse.org/api/info/applicationTermsOfUse?lang=en"
+
 Get API Terms of Use URL
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/sphinx-guides/source/installation/config.rst

@@ -3921,22 +3921,31 @@ If you don't want the datafiles to be validated on publish, set:
 
 ``curl -X PUT -d 'false' http://localhost:8080/api/admin/settings/:FileValidationOnPublishEnabled``
 
+.. _:ApplicationTermsOfUse:
 
 :ApplicationTermsOfUse
 ++++++++++++++++++++++
 
-Upload an default language HTML file containing the Terms of Use to be displayed at sign up. Supported HTML tags are listed under the :doc:`/user/dataset-management` section of the User Guide.
+Application Terms of Use (called "General Terms of Use" in the UI) are shown to the user when they sign up for an account. Some HTML tags are supported. For a list, see :ref:`supported-html-tags` in the User Guide.
 
-``curl -X PUT -d@/tmp/apptou.html http://localhost:8080/api/admin/settings/:ApplicationTermsOfUse``
+You can set terms like this:
 
-To upload a language specific Terms of Use file,
+``curl -X PUT http://localhost:8080/api/admin/settings/:ApplicationTermsOfUse --upload-file /tmp/apptou.html``
 
-``curl -X PUT -d@/tmp/apptou_fr.html http://localhost:8080/api/admin/settings/:ApplicationTermsOfUse/lang/fr``
+To delete terms:
 
-To delete language specific option,
+``curl -X DELETE http://localhost:8080/api/admin/settings/:ApplicationTermsOfUse``
+
+If :ref:`i18n` is enabled, you can set the terms per language. To set terms for a specific language ("fr", for example):
+
+``curl -X PUT http://localhost:8080/api/admin/settings/:ApplicationTermsOfUse/lang/fr --upload-file /tmp/apptou_fr.html``
+
+To delete terms for a specific language ("fr", for example):
 
 ``curl -X DELETE http://localhost:8080/api/admin/settings/:ApplicationTermsOfUse/lang/fr``
 
+To retrieve the values, see :ref:`api-get-app-tou` in the API Guide.
+
 :ApplicationPrivacyPolicyUrl
 ++++++++++++++++++++++++++++
 

doc/sphinx-guides/source/user/dataset-management.rst

@@ -64,10 +64,10 @@ Adding a New Dataset
 
 Note: You can add additional metadata once you have completed the initial dataset creation by going to clicking the Edit button and selecting Metadata from the dropdown menu.
 
-.. _supported-html-fields:
+.. _supported-html-tags:
 
-Supported HTML Fields
----------------------
+Supported HTML Tags
+-------------------
 
 We currently only support the following HTML tags for any of our textbox metadata fields (i.e., Description) : <a>, <b>, <blockquote>, 
 <br>, <code>, <del>, <dd>, <dl>, <dt>, <em>, <hr>, <h1>-<h3>, <i>, <img>, <kbd>, <li>, <ol>, <p>, <pre>, <s>, <sup>, <sub>, 

src/main/java/edu/harvard/iq/dataverse/api/Info.java

@@ -26,10 +26,13 @@
 import jakarta.json.JsonValue;
 import jakarta.ws.rs.GET;
 import jakarta.ws.rs.Path;
-import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.QueryParam;
 import jakarta.ws.rs.core.MediaType;
 import jakarta.ws.rs.core.Response;
 import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.enums.SchemaType;
+import org.eclipse.microprofile.openapi.annotations.media.Schema;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
 import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
 import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
@@ -78,6 +81,19 @@ public Response getServer() {
         return ok(JvmSettings.FQDN.lookup());
     }
 
+    @GET
+    @Path("applicationTermsOfUse")
+    @APIResponse(responseCode = "200",
+                 description = "Application Terms of Use (General Terms of Use) that must be agreed to at signup.")
+    public Response getApplicationTermsOfUse(
+            @Parameter(description = "Two-character language code.",
+                    required = false,
+                    example = "en",
+                    schema = @Schema(type = SchemaType.STRING))
+            @QueryParam("lang") String lang) {
+        return ok(systemConfig.getApplicationTermsOfUse(lang));
+    }
+
     @GET
     @Path("apiTermsOfUse")
     public Response getTermsOfUse() {

src/main/java/edu/harvard/iq/dataverse/util/SystemConfig.java

@@ -428,15 +428,24 @@ public boolean isThumbnailGenerationDisabledForPDF() {
     }
 
     public String getApplicationTermsOfUse() {
-        String language = BundleUtil.getCurrentLocale().getLanguage();
+        return getApplicationTermsOfUse(null);
+    }
+
+    public String getApplicationTermsOfUse(String languageIn) {
+        String language = null;
+        if (languageIn != null) {
+            language = languageIn;
+        } else {
+            language = BundleUtil.getCurrentLocale().getLanguage();
+        }
         String saneDefaultForAppTermsOfUse = BundleUtil.getStringFromBundle("system.app.terms");
-        // Get the value for the defaultLocale. IT will either be used as the return
+        // Get the value for the defaultLocale. It will either be used as the return
         // value, or as a better default than the saneDefaultForAppTermsOfUse if there
         // is no language-specific value
         String appTermsOfUse = settingsService.getValueForKey(SettingsServiceBean.Key.ApplicationTermsOfUse, saneDefaultForAppTermsOfUse);
-        //Now get the language-specific value if it exists
+        // Now get the language-specific value if it exists
         if (language != null && !language.equalsIgnoreCase(BundleUtil.getDefaultLocale().getLanguage())) {
-            appTermsOfUse = settingsService.getValueForKey(SettingsServiceBean.Key.ApplicationTermsOfUse, language,	appTermsOfUse);
+            appTermsOfUse = settingsService.getValueForKey(SettingsServiceBean.Key.ApplicationTermsOfUse, language, appTermsOfUse);
         }
         return appTermsOfUse;
     }

src/test/java/edu/harvard/iq/dataverse/api/InfoIT.java

@@ -3,6 +3,7 @@
 import static io.restassured.RestAssured.given;
 import io.restassured.response.Response;
 import edu.harvard.iq.dataverse.settings.SettingsServiceBean;
+import edu.harvard.iq.dataverse.util.BundleUtil;
 import org.junit.jupiter.api.AfterAll;
 import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Test;
@@ -13,6 +14,7 @@
 import java.nio.file.Paths;
 import static org.hamcrest.CoreMatchers.equalTo;
 import static org.hamcrest.CoreMatchers.notNullValue;
+import org.junit.jupiter.api.Disabled;
 import org.skyscreamer.jsonassert.JSONAssert;
 
 public class InfoIT {
@@ -21,6 +23,8 @@ public class InfoIT {
     public static void setUpClass() {
         UtilIT.deleteSetting(SettingsServiceBean.Key.MaxEmbargoDurationInMonths);
         UtilIT.deleteSetting(SettingsServiceBean.Key.DatasetPublishPopupCustomText);
+        UtilIT.deleteSetting(SettingsServiceBean.Key.ApplicationTermsOfUse);
+        UtilIT.deleteSetting(SettingsServiceBean.Key.ApplicationTermsOfUse, "fr");
     }
 
     @AfterAll
@@ -58,7 +62,52 @@ public void testGetServer() {
     }
 
     @Test
-    public void testGetTermsOfUse() {
+    public void testGetAppTermsOfUse() {
+        Response getTermsUnset = UtilIT.getAppTermsOfUse();
+        getTermsUnset.prettyPrint();
+        getTermsUnset.then().assertThat().statusCode(OK.getStatusCode())
+                .body("data.message", equalTo(BundleUtil.getStringFromBundle("system.app.terms")));
+
+        String terms = "Be excellent to each other.";
+
+        Response setTerms = UtilIT.setSetting(SettingsServiceBean.Key.ApplicationTermsOfUse, terms);
+        setTerms.prettyPrint();
+        setTerms.then().assertThat().statusCode(OK.getStatusCode());
+
+        Response getTermsSet = UtilIT.getAppTermsOfUse();
+        getTermsSet.prettyPrint();
+        getTermsSet.then().assertThat().statusCode(OK.getStatusCode())
+                .body("data.message", equalTo(terms));
+
+        Response getTermsEn = UtilIT.getAppTermsOfUse("en");
+        getTermsEn.prettyPrint();
+        getTermsEn.then().assertThat().statusCode(OK.getStatusCode())
+                .body("data.message", equalTo(terms));
+    }
+
+    /**
+     * Disabled because internationalization isn't set up.
+     */
+    @Disabled
+    @Test
+    public void testGetAppTermsOfUseFrench() {
+        Response getTermsUnsetFr = UtilIT.getAppTermsOfUse("fr");
+        getTermsUnsetFr.prettyPrint();
+        getTermsUnsetFr.then().assertThat().statusCode(OK.getStatusCode())
+                .body("data.message", equalTo(BundleUtil.getStringFromBundle("system.app.terms")));
+
+        Response setTermsFr = UtilIT.setSetting(SettingsServiceBean.Key.ApplicationTermsOfUse, "Appelez-moi.", "fr");
+        setTermsFr.prettyPrint();
+        setTermsFr.then().assertThat().statusCode(OK.getStatusCode());
+
+        Response getTermsFr = UtilIT.getAppTermsOfUse("fr");
+        getTermsFr.prettyPrint();
+        getTermsFr.then().assertThat().statusCode(OK.getStatusCode())
+                .body("data.message", equalTo("Appelez-moi."));
+    }
+
+    @Test
+    public void testGetApiTermsOfUse() {
         Response response = given().urlEncodingEnabled(false)
                 .get("/api/info/apiTermsOfUse");
         response.prettyPrint();

src/test/java/edu/harvard/iq/dataverse/api/UtilIT.java

@@ -2398,6 +2398,11 @@ static Response deleteSetting(SettingsServiceBean.Key settingKey) {
         return response;
     }
 
+    static Response deleteSetting(SettingsServiceBean.Key settingKey, String language) {
+        Response response = given().when().delete("/api/admin/settings/" + settingKey + "/lang/" + language);
+        return response;
+    }
+
     /**
      * @param settingKey Include the colon like :BagItLocalPath
      */
@@ -2416,6 +2421,11 @@ static Response setSetting(SettingsServiceBean.Key settingKey, String value) {
         return response;
     }
 
+    static Response setSetting(SettingsServiceBean.Key settingKey, String value, String language) {
+        Response response = given().body(value).when().put("/api/admin/settings/" + settingKey + "/lang/" + language);
+        return response;
+    }
+
     /**
      * @param settingKey Include the colon like :BagItLocalPath
      */
@@ -2861,6 +2871,18 @@ static Response downloadFromUrl(String url) {
         return given().get(url);
     }
 
+    static Response getAppTermsOfUse() {
+        return getAppTermsOfUse(null);
+    }
+
+    static Response getAppTermsOfUse(String lang) {
+        String optionalLang = "";
+        if (lang != null) {
+            optionalLang = "?lang=" + lang;
+        }
+        return given().get("/api/info/applicationTermsOfUse" + optionalLang);
+    }
+
     static Response metricsDataversesToMonth(String yyyymm, String queryParams) {
         String optionalYyyyMm = "";
         if (yyyymm != null) {