686584 - Documentation omissions

Status: VERIFIED WONTFIX

(Cloud Services Graveyard :: Server: Sync, defect)

Description

[Richard Newman [:rnewman]]

Answers needed, and good to see these in the docs here:

http://docs.services.mozilla.com/storage/apis-1.1.html


In particular:

* DELETE https://server/pathname/version/username/storage/collection

Response not documented. JSON? Timestamp? Empty body? 204?

What happens if the collection doesn't exist?

* DELETE https://server/pathname/version/username/storage/collection/id

Same, and what happens if the WBO doesn't exist?

* PUT https://server/pathname/version/username/storage/collection/id

Be explicit about the encoding (e.g., JSON) of the response.

* GET https://server/pathname/version/username/storage/collection

Be explicit about the encoding (e.g., JSON) of the response. Provide examples for each kind of response.

* Throughout:

  "Returns a hash of collections…"

The appropriate JSON term is "object". I'd accept "map" or "associative collection". "Hash" isn't really the right word here.

* "The number of seconds to keep this record. After that time, this item will not be returned."

Be clear: "be returned in queries to a collection"? Can you still get the item by ID? Is it deleted?

Comment 1

[Tarek Ziadé (:tarek)]

(In reply to Richard Newman [:rnewman] from comment #0)
> Answers needed, and good to see these in the docs here:
> 
> http://docs.services.mozilla.com/storage/apis-1.1.html
> 
> 
> In particular:
> 
> * DELETE https://server/pathname/version/username/storage/collection
> 
> Response not documented. JSON? Timestamp? Empty body? 204?

As said at the beginning of the doc, Request and response bodies are all JSON-encoded.

That particular API returns 'true' or 'false'  *added in the doc patch


> What happens if the collection doesn't exist?

It returns 'false'


> * DELETE https://server/pathname/version/username/storage/collection/id
> 
> Same, and what happens if the WBO doesn't exist?

Same behavior

> * PUT https://server/pathname/version/username/storage/collection/id
> 
> Be explicit about the encoding (e.g., JSON) of the response.

All requests are in JSON, as said in the beginning of the document.

Maybe we could add an example ?

> * GET https://server/pathname/version/username/storage/collection
> 
> Be explicit about the encoding (e.g., JSON) of the response. Provide
> examples for each kind of response.

Adding some examples

> 
> * Throughout:
> 
>   "Returns a hash of collections…"
> 
> The appropriate JSON term is "object". I'd accept "map" or "associative
> collection". "Hash" isn't really the right word here.

a mapping of hashes maybe ?

> 
> * "The number of seconds to keep this record. After that time, this item
> will not be returned."
> 
> Be clear: "be returned in queries to a collection"? Can you still get the
> item by ID? Is it deleted?

no it's not deleted, the ttl option is just a filter option. I am not sure how to change this sentence to make it clearer

Building a doc patch with examples and the mentioned fixes for now

Comment 2

[Ryan Kelly [:rfkelly]]

This is old sync1.1 era news, please re-open if we have similar omissions i the sync1.5 docs.

Comment 3

[James Bonacci [:jbonacci]]

Yep. And we have an open "meta" doc bug just for that purpose...