rewrite doc to follow standard format #441
Conversation
|
This PR rewrites observation.md to follow the standard format of the other API docs, as specified in https://github.com/datacommonsorg/docsite/blob/master/api/rest/v1/_rest_api_template.md. This includes:
It also:
Staged at bullie.svl.corp.google.com:4000 |
api/rest/v2/observation.md
Outdated
| | key <br /> <required-tag>Required</required-tag> | string | Your API key. See the [page on authentication](/api/rest/v2/getting_started.html#authentication) for a demo key, as well as instructions on how to get your own key. | | ||
| | date <br /> <required-tag>Required</required-tag> | string | See [below](#date-string) for allowable values. | | ||
| | variable.dcids <br /> <required-tag>Required</required-tag>| list of strings | List of [DCIDs](/glossary.html#dcid) for the statistical variable to be queried. | | ||
| | entity.dcids | list of strings | Comma-separated list of [DCIDs](/glossary.html#dcid) of entities to query. At least one of `entity.dcids` or `entity.expression` is required. | |
There was a problem hiding this comment.
instead of At least one of entity.dcids or entity.expression is required, should it be One of entity.dcids or entity.expression is required? because I don't think we can have both, can we?
There was a problem hiding this comment.
Yes, you can, as described later.
There was a problem hiding this comment.
oh interesting, where is this described?
There was a problem hiding this comment.
Whoops, I mixed this up with the select stuff. D'oh! It seemed like it should work (like I want the person count for Pittsburgh and all cities contained in California), but I just tried it and you're right, it doesn't actually work. It's not rejected as an invalid query, but entity.dcids seems to always take precedence (I tested using 2 orders). Do you think this is intended behavior or a bug?
There was a problem hiding this comment.
I've always assumed you can only do one or the other, but I'm not sure if that was the intention ..
There was a problem hiding this comment.
OK, so for now, I've corrected the text with the current behavior. When Bo gets back I'll try to remember to ask him if this is intended behavior. (Ideally it seems to me that you should be able to combine them, as you can have multiple entity.dcids)
There was a problem hiding this comment.
this sounds good to me
Another fix from Jennifer
No description provided.