docs: Documented revamped setting base URLs (#1043)

box · May 23, 2022 · a9cccb3 · a9cccb3
1 parent b9c5d31
commit a9cccb3
Show file tree

Hide file tree

Showing 2 changed files with 120 additions and 78 deletions.
diff --git a/doc/configuration.md b/doc/configuration.md
@@ -3,60 +3,76 @@ Configuration
 
 - [URLs configuration](#urls-configuration)
     - [Base URL](#base-url)
+    - [Base Upload URL](#base-upload-url)
     - [Base App URL](#base-app-url)
-    - [Token URL](#token-url)
-    - [Revoke URL](#revoke-url)
-    - [Upload URL](#upload-url)
+    - [Token URL](#token-url-deprecated)
+    - [Revoke URL](#revoke-url-deprecated)
 
 URLs configuration
 ------------------
 
 ### Base URL
-The default base URL used for making API calls to Box can be changed by calling `setBaseURL()` 
-method on `BoxApiConnection`. Default value is https://api.box.com/2.0/.
+The default base URL used for making API calls to Box can be changed by calling `BoxAPIConnection#setBaseURL(String)` 
+method on `BoxApiConnection`. Default value is `https://api.box.com/`.
 
 ```java
 BoxAPIConnection api = new BoxAPIConnection("YOUR-DEVELOPER-TOKEN");
 
 api.setBaseURL("https://example.com");
+String baseUrl = api.getBaseURL();    // will produce "https://example.com/2.0/"
+```
+
+Setting Base URL changes the Token and Revoke URL as well:
+```java
+BoxAPIConnection api = new BoxAPIConnection("YOUR-DEVELOPER-TOKEN");
+
+api.setBaseURL("https://example.com");
+
+String baseUrl = api.getBaseURL();    // will produce "https://example.com/2.0/"
+String tokenUrl = api.getRevokeURL(); // will produce "https://example.com/oauth2/revoke"
+String revokeUrl = api.getTokenURL(); // will produce "https://example.com/oauth2/token"
+```
+
+### Base Upload URL
+The default URL used for uploads can be changed by calling `BoxAPIConnection#setBaseUploadURL(String)` method on `BoxApiConnection`.
+Default value is `https://upload.box.com/api/`.
+
+```java
+BoxAPIConnection api = new BoxAPIConnection("YOUR-DEVELOPER-TOKEN");
+
+api.setBaseUploadURL("https://upload.example.com");
+api.getBaseUploadURL(); // will produce "https://upload.example.com/2.0/"
 ```
 
 ### Base App URL
-The default base app URL can be changed by calling `setBaseAppUrl()` method on `BoxApiConnection`. 
+The default base app URL can be changed by calling `BoxAPIConnection#setBaseAppUrl()` method on `BoxApiConnection`. 
 Default value is https://app.box.com.
 
 ```java
 BoxAPIConnection api = new BoxAPIConnection("YOUR-DEVELOPER-TOKEN");
 
 api.setBaseAppUrl("https://example.app.com");
+api.getBaseAppUrl(); // will produce "https://app.example.com"
 ```
 
-### Token URL
+### Token URL (deprecated)
 The default URL used for getting token can be changed by calling `setTokenURL()` method on `BoxApiConnection`. 
-Default value is https://api.box.com/oauth2/token.
+Default value is https://api.box.com/oauth2/token. This metod is deprecated. Use `BoxAPIConnection#setBaseURL(String)` 
+instead.
 
 ```java
 BoxAPIConnection api = new BoxAPIConnection("YOUR-DEVELOPER-TOKEN");
 
 api.setTokenURL("https://example.com/token");
 ```
 
-### Revoke URL
+### Revoke URL (deprecated)
 The default URL used for invalidating token can be changed by calling `setRevokeURL()` method on `BoxApiConnection`. 
-Default value is https://api.box.com/oauth2/revoke.
+Default value is https://api.box.com/oauth2/revoke. This metod is deprecated. Use `BoxAPIConnection#setBaseURL(String)`
+instead.
 
 ```java
 BoxAPIConnection api = new BoxAPIConnection("YOUR-DEVELOPER-TOKEN");
 
 api.setRevokeURL("https://example.com/revoke");
 ```
-
-### Upload URL
-The default URL used for uploads can be changed by calling `setBaseUploadURL()` method on `BoxApiConnection`. 
-Default value is https://upload.box.com/api/2.0/.
-
-```java
-BoxAPIConnection api = new BoxAPIConnection("YOUR-DEVELOPER-TOKEN");
-
-api.setBaseUploadURL("https://example.upload.com");
-```
diff --git a/doc/users.md b/doc/users.md
@@ -1,5 +1,4 @@
-Users
-=====
+# Users
 
 Users represent an individual's account on Box.
 
@@ -8,6 +7,10 @@ Users represent an individual's account on Box.
 
 
 - [Get the Current User's Information](#get-the-current-users-information)
+- [Get User Information](#get-user-information)
+- [Get Avatar for a User](#get-avatar-for-a-user)
+- [Add or update user avatar](#add-or-update-user-avatar)
+- [Delete user avatar](#delete-user-avatar)
 - [Create An Enterprise User](#create-an-enterprise-user)
 - [Create An App User](#create-an-app-user)
 - [Update User](#update-user)
@@ -24,8 +27,7 @@ Users represent an individual's account on Box.
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-Get the Current User's Information
-----------------------------------
+## Get the Current User's Information
 
 To get the current user, call the static
 [`getCurrentUser(BoxAPIConnection api)`][get-current-user] method.
@@ -37,11 +39,10 @@ BoxUser user = BoxUser.getCurrentUser(api);
 BoxUser.Info info = user.getInfo();
 ```
 
-[get-current-user]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getCurrentUser-com.box.sdk.BoxAPIConnection-
-[get-info]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getInfo-java.lang.String...-
+[get-current-user]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getCurrentUser-com.box.sdk.BoxAPIConnection-
+[get-info]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getInfo-java.lang.String...-
 
-Get User Information
---------------------
+## Get User Information
 
 To get information about a user, call the [`getInfo()`][get-info] method on the user object.
 
@@ -52,10 +53,9 @@ BoxUser user = new BoxUser(api, userID);
 BoxUser.Info userInfo = user.getInfo();
 ```
 
-Get Avatar for a User
----------------------
+## Get Avatar for a User
 
-To retrieve the avatar for a user, call the [`getAvatar()`][get-avatar] method on the user object.
+To retrieve the avatar for a User, call the [`getAvatar()`][get-avatar] method on the user object.
 
 <!-- sample get_users_id_avatar -->
 ```java
@@ -64,10 +64,48 @@ BoxUser user = new BoxUser(api, userID);
 InputStream avatarStream = user.getAvatar();
 ```
 
-[get-avatar]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAvatar--
+## Add or update user avatar
 
-Create An Enterprise User
--------------------------
+To add or update the avatar for a User, call the [`uploadAvatar(File)`][upload-avatar-1] method on the user object.
+
+<!-- sample post_users_id_avatar -->
+```java
+String userID = "33333";
+BoxUser user = new BoxUser(api, userID);
+AvatarUploadResponse response = user.uploadAvatar(new File("path_to_avatar_file"));
+```
+In return, you will get an object with links to several representations of an avatar within Box account. 
+Your image file should have correct extension, it is used to determine image type used in upload.
+Supported formats are JPG and PNG. The image size cannot exceed 1024 * 1024 pixels or 1MB.
+
+You can upload avatart using `InputStream` with [`uploadAvatar(InputStream, String)`][upload-avatar-2]:
+
+```java
+String userID = "33333";
+BoxUser user = new BoxUser(api, userID);
+AvatarUploadResponse response = user.uploadAvatar(Files.newInputStream(Paths.get("path_to_avatar_file")), "file_name.jpeg");
+```
+
+Both upload methods supports [`ProgressListener`][progress-listener].
+
+## Delete user avatar
+
+To delete User avatar image use [`deleteAvatar()`][delete-avatar] method on the user object:
+
+<!-- sample delete_users_id_avatar -->
+```java
+String userID = "33333";
+BoxUser user = new BoxUser(api, userID);
+user.deleteAvatar();
+```
+
+[get-avatar]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAvatar--
+[upload-avatar-1]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#uploadAvatar-java.io.File-
+[upload-avatar-2]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#uploadAvatar-java.io.InputStream-java.lang.String-
+[delete-avatar]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#deleteAvatar--
+[progress-listener]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/ProgressListener.html
+
+## Create An Enterprise User
 
 To create an enterprise user, call the
 [`createEnterpriseUser(BoxAPIConnection api, String loginEmail, String userName)`][create-enterprise-user].
@@ -80,11 +118,10 @@ method.
 BoxUser.Info createdUserInfo = BoxUser.createEnterpriseUser(api, "user@example.com", "A User");
 ```
 
-[create-enterprise-user]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#createEnterpriseUser-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String-
-[create-enterprise-user-2]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#createAppUser-com.box.sdk.BoxAPIConnection-java.lang.String-com.box.sdk.CreateUserParams-
+[create-enterprise-user]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#createEnterpriseUser-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String-
+[create-enterprise-user-2]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#createAppUser-com.box.sdk.BoxAPIConnection-java.lang.String-com.box.sdk.CreateUserParams-
 
-Create An App User
-------------------
+## Create An App User
 
 To create an app user, call the
 [`createAppUser(BoxAPIConnection api, String userName)`][create-app-user] method.
@@ -102,12 +139,11 @@ params.setExternalAppUserId("An Identifier Like Login");
 BoxUser.Info createdUserInfo = BoxUser.createAppUser(api, "A User", params);
 ```
 
-[create-app-user]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#createAppUser-com.box.sdk.BoxAPIConnection-java.lang.String-
-[create-app-user-2]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#createAppUser-com.box.sdk.BoxAPIConnection-java.lang.String-com.box.sdk.CreateUserParams-
+[create-app-user]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#createAppUser-com.box.sdk.BoxAPIConnection-java.lang.String-
+[create-app-user-2]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#createAppUser-com.box.sdk.BoxAPIConnection-java.lang.String-com.box.sdk.CreateUserParams-
 
 
-Update User
------------
+## Update User
 
 To update a user call the [`updateInfo(BoxUser.Info fieldsToUpdate)`][update-info] method.
 
@@ -119,10 +155,9 @@ info.setName(name);
 user.updateInfo(info);
 ```
 
-[update-info]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#updateInfo-com.box.sdk.BoxUser.Info-
+[update-info]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#updateInfo-com.box.sdk.BoxUser.Info-
 
-Delete User
------------
+## Delete User
 
 To delete a user call the [`delete(boolean notifyUser, boolean force)`][delete] method.
 
@@ -136,10 +171,9 @@ BoxUser user = new BoxUser(api, "0");
 user.delete(false, false);
 ```
 
-[delete]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#delete-boolean-boolean-
+[delete]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#delete-boolean-boolean-
 
-Invite User
------------
+## Invite User
 
 To invite an existing user to join an Enterprise call the
 [`inviteUser(String enterpriseID, String userEmail)`][invite] method.
@@ -150,10 +184,9 @@ BoxUser user = new BoxUser(api, "0");
 user.invite("Enterprise ID", "Invited User Login");
 ```
 
-[invite]:  http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#inviteUser-java.lang.String-java.lang.String-
+[invite]:  https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#inviteUser-java.lang.String-java.lang.String-
 
-Get Email Aliases
------------------
+## Get Email Aliases
 
 To get a user's email aliases call the [`getEmailAliases()`][get-email-aliases] method.
 
@@ -163,10 +196,9 @@ BoxUser user = new BoxUser(api, "0");
 Collection<EmailAlias> emailAliases = user.getEmailAliases();
 ```
 
-[get-email-aliases]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getEmailAliases--
+[get-email-aliases]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getEmailAliases--
 
-Add Email Alias
----------------
+## Add Email Alias
 
 To add an email alias for a user, call the
 [`addEmailAlias(String emailAddress)`][add-email-alias] method.
@@ -185,11 +217,10 @@ BoxUser user = new BoxUser(api, "0");
 user.addEmailAlias("user+alias@eexample.com", true);
 ```
 
-[add-email-alias]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#addEmailAlias-java.lang.String-
-[add-email-alias2]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#addEmailAlias-java.lang.String-boolean-
+[add-email-alias]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#addEmailAlias-java.lang.String-
+[add-email-alias2]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#addEmailAlias-java.lang.String-boolean-
 
-Delete Email Alias
-------------------
+## Delete Email Alias
 
 To delete a users email alias call the
 [`deleteEmailAlias(String emailAliasID)`][delete-email-alias] method.
@@ -200,10 +231,9 @@ BoxUser user = new BoxUser(api, "0");
 user.deleteEmailAlias("123");
 ```
 
-[delete-email-alias]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#deleteEmailAlias-java.lang.String-
+[delete-email-alias]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#deleteEmailAlias-java.lang.String-
 
-Get Enterprise Users
---------------------
+## Get Enterprise Users
 
 To get an enterprise's users call the
 [`getAllEnterpriseUsers(BoxAPIConnection api)`][get-all-enterprise-users],
@@ -215,12 +245,11 @@ To get an enterprise's users call the
 Iterable<BoxUser.Info> users = BoxUser.getAllEnterpriseUsers(api);
 ```
 
-[get-all-enterprise-users]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseUsers-com.box.sdk.BoxAPIConnection-
-[get-all-enterprise-users-2]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseUsers-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-
-[get-all-enterprise-users-3]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseOrExternalUsers-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-
+[get-all-enterprise-users]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseUsers-com.box.sdk.BoxAPIConnection-
+[get-all-enterprise-users-2]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseUsers-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-
+[get-all-enterprise-users-3]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseOrExternalUsers-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-
 
-Get Enterprise Users (Marker Pagination)
---------------------
+## Get Enterprise Users (Marker Pagination)
 
 To get a list of all users in an enterprise, call the
 [`getAllEnterpriseUsers(BoxAPIConnection api, boolean usemarker, String marker)`][get-all-enterprise-users],
@@ -236,12 +265,11 @@ Iterable<BoxUser.Info> users = BoxUser.getAllEnterpriseUsers(api, true, null);
 String marker = ((BoxResourceIterable<BoxUser.Info>) users).getNextMarker();
 ```
 
-[get-all-enterprise-users]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseUsers-com.box.sdk.BoxAPIConnection-
-[get-all-enterprise-users-2]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseUsers-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-
-[get-all-enterprise-users-3]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseOrExternalUsers-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-
+[get-all-enterprise-users]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseUsers-com.box.sdk.BoxAPIConnection-
+[get-all-enterprise-users-2]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseUsers-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-
+[get-all-enterprise-users-3]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseOrExternalUsers-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-
 
-Get App Users By External App User ID
--------------------------------------
+## Get App Users By External App User ID
 
 To get app user using external app user ID, call the
 [`getAppUsersByExternalAppUserID(BoxAPIConnection api, String externalID, String... fields)`][get-app-users-by-external-app-user-id].
@@ -252,10 +280,9 @@ identifiers for those users.
 Iterable<BoxUser.Info> users = BoxUser.getAppUsersByExternalAppUserID(api, "external_app_user_id");
 ```
 
-[get-app-users-by-external-app-user-id]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAppUsersByExternalAppUserID-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-
+[get-app-users-by-external-app-user-id]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAppUsersByExternalAppUserID-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-
 
-Get App Users By External App User ID (Marker Pagination) 
--------------------------------------
+## Get App Users By External App User ID (Marker Pagination)
 
 To get app user using external app user ID, call the
 [`getAppUsersByExternalAppUserID(BoxAPIConnection api, String externalID, boolean usemarker, String marker, String... fields)`][get-app-users-by-external-app-user-id].
@@ -269,10 +296,9 @@ Iterable<BoxUser.Info> users = BoxUser.getAppUsersByExternalAppUserID(api, "exte
 String marker = ((BoxResourceIterable<BoxUser.Info>) users).getNextMarker();
 ```
 
-[get-app-users-by-external-app-user-id]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAppUsersByExternalAppUserID-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-
+[get-app-users-by-external-app-user-id]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAppUsersByExternalAppUserID-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-
 
-Move User's Folder
-------------------
+## Move User's Folder
 
 To move all of a user's content to another user, call the
 [`transferContent(String destinationUserID)`][transfer-folder-to-new-user] method.
@@ -285,4 +311,4 @@ BoxUser sourceUser = new BoxUser(api, sourceUserID);
 BoxFolder.Info transferredFolderInfo = sourceUser.transferContent(destinationUserID);
 ```
 
-[transfer-folder-to-new-user]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#transferContent-java.lang.String-
+[transfer-folder-to-new-user]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#transferContent-java.lang.String-