docs: first pass at consolidating API docs #392
Conversation
|
The docs PR has revealed some bitrot in our API unit tests: https://pantheon.corp.google.com/cloud-build/builds;region=global/b7d3be9a-68bb-4ca7-bb7e-45a2bb702f1c;step=3?project=emblem-ops These seem unrelated to this change. |
|
|
||
| 1. [Navigate to Cloud Firestore](https://console.cloud.google.com/firestore/data) | ||
| and select **Native** mode. This can only be done once, before the database is used. | ||
| 1. "Seed" the Emblem API Cloud Firestore database with the |
There was a problem hiding this comment.
Is this step necessary if we're asking users to run the seeding script?
| export EMBLEM_API_URL=$(gcloud run services describe content-api --project $PROJECT_ID --format "value(status.url)") | ||
|
|
||
| # Make an HTTP request to get a "cause" entry. | ||
| curl -X GET $EMBLEM_API_URL/causes/6aee60eead3741a98f15 |
There was a problem hiding this comment.
Nit: describe where this value (6aee60eead3741a98f15) comes from.
e.g.
# This cause ID (`6aee60eead3741a98f15` ) comes from our seeding data.
|
|
||
| You may use the Cloud Firestore emulator if working with data in the Cloud | ||
| introduces too much latency. Warning: This is not a standard workflow and these | ||
| instructions may be out of date. |
There was a problem hiding this comment.
This feels like it should be a TODO issue.
There was a problem hiding this comment.
It probably should, I'm inclined to think maybe we should reduce our docs and point to emulator docs somewhere else? We're mostly not recommending this path right now.
There was a problem hiding this comment.
Yeah - either is fine by me, so long as we log a follow-up issue.
(It can wait until after Public Preview, if need be.)
Co-authored-by: Ace Nassri <anassri@google.com>
|
Noting for reviewers: this PR moves some docs around, removes some redundant text, and clarifies a few things. It's meant as a raw first iteration. I would prefer to keep scope tight and not reopen discussions about what's been written. More PRs to improve it are very welcome! |
This is a first pass at consolidating the API service documentation. It does not include revisions to the API usage documentation.
This is an iteration towards #337