Merge pull request #202 from xmidt-org/feature/docUpdate

clarify comments about default item owner value

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ## [Unreleased]
 - Update store section in sample config files. [#200](https://github.com/xmidt-org/argus/pull/200)
 - Update sample config value so argus webhook integration works out of the box in test environments. [#203](https://github.com/xmidt-org/argus/pull/203)
+- Clarify behavior around requests that don't exercise the item owner header. [#202](https://github.com/xmidt-org/argus/pull/202)
 
 ## [v0.5.1]
 - Fix github actions config for uploading test and coverage reports for sonarcloud. [#192](https://github.com/xmidt-org/argus/pull/192)

README.md

@@ -52,7 +52,9 @@ The body must be in JSON format with the following attributes:
 * _ttl_ - Optional.  Specified in units of seconds.  Defaults to the value of the server configuration option `itemMaxTTL`. If a configuration value is not specified, the value would be a day (~ 24*60^2 seconds).
 )
 
-An optional header `X-Midt-Owner` can be sent to associate the object with an owner.  The value of this header will be bound to a new record, which would require the same value passed in a `X-Midt-Owner` header for subsequent reads or modifications.  This in effect creates a secret attribute bound to the life of newly created records. When provided, Argus validates the length of the owner string to be in the range `[10,60]`. If you'd like to define your own validation format, check out the `userInputValidation.ownerFormatRegex` configuration option.
+An optional header `X-Midt-Owner` can be sent to associate the object with an owner. The value of this header will be bound to the new item, which would require the same value passed in a `X-Midt-Owner` header for subsequent reads or modifications. This in effect creates a secret attribute bound to the life of newly created items. When provided, Argus validates the length of the owner string to be in the range `[10,60]`. If you'd like to define your own validation format, check out the `userInputValidation.ownerFormatRegex` configuration option.
+
+When the header is not provided, the owner of the item will be the empty string.
 
 The exception to the above would be an authorized request.  The authorization method is not specified and is up to the implementation to decide.  Authorized requests shall be allowed to update all attributes except the `X-Midt-Owner` meta attribute.
 
@@ -86,7 +88,7 @@ The above response would indicate an existing object has been updated (existing
 ### List - `store/{bucket}` endpoint
 This endpoint allows for `GET` to retrieve all the items in the bucket organized by the id.
 
-An example response will look like the below where "7e8c5f378b4addbaebc70897c4478cca06009e3e360208ebd073dbee4b3774e7" is the id of the only item in this collection. An optional header `X-Midt-Owner` can be sent with the request.  If supplied, only items with secrets matching the supplied value will be returned in the list. Only authorized requests can retrieve items from all owners.
+An example response will look like the below where "7e8c5f378b4addbaebc70897c4478cca06009e3e360208ebd073dbee4b3774e7" is the id of the only item in this collection. An optional header `X-Midt-Owner` can be sent with the request.  If supplied, only items with secrets matching the supplied value will be returned in the list. If not supplied, all items created without an owner (owner value = "") will be returned. For authorized requests, if no owner header is provided, all items for the specified bucket will be returned.
 
 An example response:
 ```json
@@ -109,7 +111,7 @@ An example response:
 
 
 ### Individual Item - `store/{bucket}/{id}` endpoint
-This endpoint allows for `GET`, and `DELETE` REST methods to interact with any object that was created with the previous `PUT` request.  An optional header `X-Midt-Owner` can be sent with the request.  All requests are validated by comparing the secret stored with the requested record with the value sent in the `X-Midt-Owner` header.  If the header is missing, `nil` is assigned to comparison value.  A mismatch will result in a "403 Forbidden" error.  An authorized request may override this requirement, providing an administrative override.  The method of authorization is not specified.
+This endpoint allows for `GET`, and `DELETE` REST methods to interact with any object that was created with the previous `PUT` request.  An optional header `X-Midt-Owner` can be sent with the request.  All requests are validated by comparing the secret stored with the requested record with the value sent in the `X-Midt-Owner` header.  If the header is missing, the "" (empty string) is assigned as the item's owner during item creation.  A mismatch will result in a "403 Forbidden" error.  An authorized request may override this requirement, providing an administrative override.  The method of authorization is not specified.
 
 An example response:
 ```json