Create API_overview.md #22
Conversation
API overview document draft
✅ Deploy Preview for chronologue ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
There was a problem hiding this comment.
Thanks for your work on this @valeriahhdez 🎖️
I've left some comments for you and @fineon (and me :D) so we can clarify some parts a bit more.
API_overview.md
Outdated
| ## About the Chronologue API | ||
| <br> | ||
|
|
||
| The Chronologue API is open-source software that stores data about astronomical events. You can easily query astronomical data stored in the API and visualize events on the Chronologue website. |
There was a problem hiding this comment.
@fineon
Hey Ian,
I wanted to get your opinion on this opening statement. Technically, an API is rather an interface that ensures two parties (for example a server and a browser) can communicate than a data store.
What we built is a JSON file that we can query - but I think the way to fetch an entry is by using normal HTTP methods, right?
My bottom line here is: It doesn't sound technically correct to say that the API itself stores the data. I wonder how we can word it differently so it is more technically accurate.
There was a problem hiding this comment.
hmm what about The Chonologue API is an open source interface that provides astronomical and temporal events ?
There was a problem hiding this comment.
I am okay with the 2nd sentence. It is technically correct.
There was a problem hiding this comment.
Thank you both for your input! I'm still new to the field and I find myself mixing concepts so is great to have more experienced eyes catching these inaccuracies.
API_overview.md
Outdated
|
|
||
| The Chronologue API is open-source software that stores data about astronomical events. You can easily query astronomical data stored in the API and visualize events on the Chronologue website. | ||
|
|
||
| The main purpose of Chronologue API is to help scientists and organizations advance humanity's knowledge. To query and visualize an astronomical event, you need an HTTP client, for example, Chrome. |
There was a problem hiding this comment.
Minor suggestion: The query can be done via an HTTP client, that's correct.
Can you clarify what you want to express with "visualize"? I am guessing that you mean a graphical representation, like on our website (which a web browser would be a suitable HTTP client as you mentioned).
Another very small nitpick: Instead of highlighting Chrome here, I would choose a more neutral phrase like: "... you need an HTTP client, for example, a web browser. "
There was a problem hiding this comment.
Yes, your assumption is correct. My justification for why I talk about "visualization" in the overview is to situate the API within the context of "The Chronologue" project. First I answer the question "what does the Chronologue API do? It stores astronomical events data that you can query" and then I extend this a bit further "you can visualize these events on the Chronologue website".
In my mind, If I just leave it at "The Chronologue API stores astronomical data..." the reader, especially scientists, might be left with a thought of "and then what?"
I hope it makes sense : )
There was a problem hiding this comment.
In our Slack conversation, Ian answered this question. At the moment, the API sends the response to the Chronologue website. I therefore assumed that the only way to use this data is to visualize the event it contains. Please correct me if this is wrong. Is it possible for the user to query astronomical data, receive it via the Chronologue website and not visualize it?
API_overview.md
Outdated
| Developers can contribute to the software by joining the Chronologue Project, which is part of The Good Docs project. To contribute to program code, you should be familiar with the following tools: | ||
|
|
||
| - Next.js | ||
| - Netlify hosting infrastructure | ||
|
|
||
| To learn more, join our [Slack community](https://thegooddocs.slack.com/) or attend a [Chronologue meeting](https://thegooddocsproject.dev/community/). |
There was a problem hiding this comment.
Context: At some point, we need to create a contribution guide, similar to what the template team has: Template Contribution Guide
For now, I would place this section probably at the end of the document, since the main goal of the document is to get an overview, first. After people have a good idea of what they are dealing with, they might be happy to contribute.
API_overview.md
Outdated
|
|
||
| To use the Chronologue API, read and follow the steps described in the "Request for a new recording" document. If your request is approved, you will receive a notification email containing an API Key that gives you access to the Chronologue's API. | ||
|
|
||
| The Chronologue API follows REST architecture. You can access the API's resources via HTTP requests and responses are given in JSON format. |
There was a problem hiding this comment.
I would put this information into either the overview or higher up in main features. :)
| Gather information with the Chronologue API to further humanity's understanding. You can visualize past events that can help you explain what circumstances caused a another phenomenon of nature. | ||
|
|
||
| Use the Chronologue API to test your hypothesis. The Chronologue API can make predictions about future astronomical events. You can compare your predictions to those prouced by the API as a way to validate your hypothesis. |
API_overview.md
Outdated
| <br> | ||
| <br> | ||
|
|
||
| ## Common use cases |
There was a problem hiding this comment.
I wonder if we need subheadings.
We could also structure it a bit more lean like:
| ## Common use cases | |
| ## Use cases | |
| Chronologue's main purpose is to further humanity's body of knowledge. Some common use cases include: | |
| - Use case | |
| - Use case | |
| - Use case |
There was a problem hiding this comment.
Sound ok to me.
Adding Tina's rephrasing Co-authored-by: Tina Luedtke <[email protected]>
Change H4 ->H3 Co-authored-by: Tina Luedtke <[email protected]>
H4 ->H3 Co-authored-by: Tina Luedtke <[email protected]>
First reviewed
API_overview.md
Outdated
| <br> | ||
| <br> | ||
|
|
||
| ## Common use cases |
There was a problem hiding this comment.
Sound ok to me.
API_overview.md
Outdated
|
|
||
| The Chronologue API is open-source software that stores data about astronomical events. You can easily query astronomical data stored in the API and visualize events on the Chronologue website. | ||
|
|
||
| The main purpose of Chronologue API is to help scientists and organizations advance humanity's knowledge. To query and visualize an astronomical event, you need an HTTP client, for example, Chrome. |
There was a problem hiding this comment.
In our Slack conversation, Ian answered this question. At the moment, the API sends the response to the Chronologue website. I therefore assumed that the only way to use this data is to visualize the event it contains. Please correct me if this is wrong. Is it possible for the user to query astronomical data, receive it via the Chronologue website and not visualize it?
API_overview.md
Outdated
|
|
||
| To use the Chronologue API, read and follow the steps described in the "Request for a new recording" document. If your request is approved, you will receive a notification email containing an API Key that gives you access to the Chronologue's API. | ||
|
|
||
| The Chronologue API follows REST architecture. You can access the API's resources via HTTP requests and responses are given in JSON format. |
API_overview.md
Outdated
|
|
||
|
|
||
|
|
||
| ) |
There was a problem hiding this comment.
I changed the name to "Request for new recording" to be consistent with the terminology Peter used in his document.
Workflow link update
API overview document draft