Add Optional Base64 Encoding Blurb (#4381)

* Add Optional Base64 Encoding Blurb 

Update description with optional Base64 instructions and links to cURL and raw Base64 examples for individual PDFs.

The team decided to call out this option in the description because it works differently from the benefits-intake API and it generated some confusion among users. The proposed change addresses the issue.

@bastosmichael feel free to change write-up if we need to add any more details.

* same content clarification as v1

Co-authored-by: Ryan Link <47920994+ryanlink@users.noreply.github.com>

modules/claims_api/app/swagger/claims_api/description/v0.md

@@ -1,8 +1,12 @@
-The Benefits Claims API allows authenticated, authorized individuals (Veterans or their representatives) to digitally submit and automatically establish certain claims, along with supporting documentation. It also allows those users to check claims’ current status.
+The Benefits Claims API allows authenticated individuals (Veterans or their authorized representatives) to digitally submit and automatically establish certain claims, along with supporting documentation. It also allows those users to see information about current claims, including their status.
 
-Internal VA consumers such as mail processing vendors can use an organizational token to establish disability compensation claims automatically.
+Internal VA consumers, such as mail processing vendors, can use an organizational token to establish disability compensation claims automatically.
+
+Whereas the [Benefits Intake API](https://developer.va.gov/explore/benefits/docs/benefits?version=current) is primarily for uploading claim-related PDFs to the Centralized Mail Portal, the Benefits Claims API can accept JSON for automatically establishing claims. Automatic establishment helps eligible Veterans receive their benefits more quickly by:
+
+1) reducing processing time by a number of days
+2) making claims immediately accessible to Veteran Service Representatives (VSRs) using the Veterans Benefits Management System (VBMS)
 
-Whereas the Benefits Intake API sends PDFs to be uploaded to the Centralized Mail Portal, the Benefits Claims API accepts more data, using it to automatically establish those claims so they're immediately accessible to Veteran Service Representatives in VBMS (Veterans Benefits Management System). This bypasses about 10 days of processing time.
 
 Currently, the API supports automatic establishment of: 
 
@@ -13,7 +17,6 @@ Currently, the API supports automatic establishment of:
  Visit our VA Lighthouse [support portal](https://developer.va.gov/support) for further assistance.
 
 ## Technical Summary
-
 The Benefits Claims API accepts a payload consisting of [JSON API compliant](https://jsonapi.org/) requests and responses on a per-form basis. The payload describes the form and identifies the person for whom it is being submitted.
 
 Some forms allow or require supporting documents to be uploaded, encoded as binary multipart/form data. 
@@ -25,24 +28,44 @@ API consumers are encouraged to validate the JSON Schema before submission, acco
 ## Design
 
 ### Authentication
-The Veteran's SSN, first name, last name, and date of birth are required alongside the API key and a level of assurance header. 
 
-The organizational keys for this API are meant for **internal** VA use only. The API assumes that those given production access to systems using a key are already authorized and validated.
+The Veteran's SSN, first name, last name, and date of birth are required alongside the API key and a level of assurance header.
+
+The organizational keys for v0 of this API are meant for internal VA use only. The API assumes that those given production access to systems using a key are already authorized and validated.
 
 **External users** (such as Veteran Service Officers, Attorneys, Claims Agents, or Veterans) authenticate using an OAuth token issued at the individual level. To learn more about this authentication path, select Version 1.0.0 from the drop-down menu above.
 
 
+#### Additional Resources
+*   A guide to [OAuth (OpenID Connect) for VA Lighthouse APIs](https://developer.va.gov/explore/health/docs/authorization)
+*   [Sample applications](https://github.com/department-of-veterans-affairs/vets-api-clients/tree/master/samples) showing this authentication model in use
+
+
+#### OAuth Scopes for Benefits Claims API
+*   `claim.read`
+    *   This scope is required for any /claims GET endpoints
+*   `claim.write`
+    *   This scope is required for any form auto-establishment endpoints
+
+
 ### Attachment & File Size Limits
-There is not a limit on the number of documents that can be submitted at once, but file sizes can impact the number of documents accepted.
 
-The file size limit for each document is 100 MB. The entire package, which is all documents combined into one file, is limited to 5 GB.
+Uploaded documents cannot be larger than 11" x 11".
 
-Documents must be within the dimensions of 11" x 11".
+A payload of documents cannot exceed 5 GB, and no single file in a payload can exceed 100 MB. There is no limit on the _number_ of files that can be contained in one payload, only the aforementioned size limitations.
 
 
 ### Bypassing 21-526 PDF Generation
+
 By default, the API generates PDFs of form 21-526 based on incoming data. Internal VA users may bypass this PDF generation to avoid creating duplicate documents.
 
+###  Optional Base64 Encoding
+
+We allow Base64 encoding to convert binary data into text format for secure transmission. You will need to encode each _individual_ 526 form rather than the whole payload.  This differs from base64 encoding for the Benefits Intake API.
+
+- There is a cURL example in the documentation for the [PUT /forms/526/{id}](#operations-Disability-upload526Attachment) endpoint. 
+
+-  If you would prefer to see a test payload, there is a [raw Base64 example](https://raw.githubusercontent.com/department-of-veterans-affairs/vets-api/master/modules/claims_api/spec/fixtures/base64pdf) you can decode and reverse engineer using the following header: `Content-Type: multipart/form-data; boundary=WebKitFormBoundaryVfOwzCyvug0JmWYo` Important note: the binary file is encoded within this base64 payload as well.
 
 ### Mock Data in Test Environments 
-Mock data is used for all forms in the Development environment, and for 21-526 submissions in the Staging environment.
+Mock data is used for all forms in the sandbox environment, and for 21-526 submissions in the Staging environment.  (Access to the Staging environment is only provided by special arrangement; the typical onboarding process goes directly from sandbox to the production API environment.)