Skip to content
This repository has been archived by the owner on Sep 24, 2022. It is now read-only.

Create API_overview.md #22

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Create API_overview.md #22

Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
595a561
Create API_overview.md
valeriahhdez Jul 22, 2022
91c4764
Update API_overview.md
valeriahhdez Aug 28, 2022
b15766c
Update API_overview.md
valeriahhdez Aug 28, 2022
6a9e3d7
Update API_overview.md
valeriahhdez Aug 28, 2022
6a4a270
Update API_overview.md
valeriahhdez Sep 19, 2022
17adeea
Update API_overview.md
valeriahhdez Sep 19, 2022
9d49920
Update API_overview.md
valeriahhdez Sep 19, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions API_overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@

valeriahhdez marked this conversation as resolved.
Show resolved Hide resolved
## 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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm what about The Chonologue API is an open source interface that provides astronomical and temporal events ?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am okay with the 2nd sentence. It is technically correct.

Copy link
Collaborator Author

@valeriahhdez valeriahhdez Aug 28, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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. "

Copy link
Collaborator Author

@valeriahhdez valeriahhdez Aug 28, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 : )

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?


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/).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure thing!


<br>

## Main features
<br>

The Chronologue time travel telescope records astronomical events of the past and future. It stores the events in the [data.json](https://github.com/thegooddocsproject/chronologue/blob/main/data/data.json) file as event objects. You can use the Chronologue API to query exisiting astronomical events from the `data.json file`.
If you want to retrieve data for an event that does not yet exist, you need to request a new recording.

> Note: The Chronologue telescope predicts future events, but the accuracy of these predictions is not guaranteed.

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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe that you can make GET requests also without going through the request for new recording, so I would just link to that document in a related links section at the bottom. :)

CC: @fineon What do you think: Do we need to hand out API keys to make GET requests?


The Chronologue API follows REST architecture. You can access the API's resources via HTTP requests and responses are given in JSON format.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would put this information into either the overview or higher up in main features. :)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!



<br>



![Chronologue API workflow]([https://drive.google.com/drive/u/0/folders/14g-_MmJNaUcYEs6nGl15Er5_Yj9JsCLS](https://drive.google.com/file/d/1QbjvwEExwCyPqTe0YeRo65lyi5g3pfo5/view?usp=sharing))
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for creating a graphic! It might be a good opener for the section.

The only thing I find hard to understand is what we mean by "visualization request".
I would assume that more technical people are using the Chronologue API, so they might not need a visualization (that's what the website already does).

I am guessing that a reader of this document might want to know what requests they can make against the API, for example GET requests or POST requests. We can also highlight that for GET requests, you don't need to be authorized, but for POST, you might need a key. I'm just thinking out loud here, maybe @fineon has some ideas as well.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I changed the name to "Request for new recording" to be consistent with the terminology Peter used in his document.

A high-level diagram of the Chronologue API's workflow.



<br>
<br>

## Common use cases
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we need subheadings.

We could also structure it a bit more lean like:

Suggested change
## 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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sound ok to me.

<br>

### Academic research

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.
Comment on lines +43 to +45
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Love these use cases! 👍


<br>

### Educational purposes

Demonstrate to your audience the causal relationship between two natural events. For example, you can show your students the asteroid's impact on Earth during the Cretaceous Period that caused the mass extinction of three-quarters of plant and animal species.