Skip to content
Snippets Groups Projects
Commit 7816a269 authored by Torgrim's avatar Torgrim
Browse files

Markdown Files updated with the latest project information. 

 Renamed and moved to support Github/GitLab readme.md tabs.
parent da9767a1
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
readme/conduct.md → CODE_OF_CONDUCT.md
+ 0
− 0
View file @ 7816a269
File moved
readme/contribute.md → CONTRIBUTING.md
+ 2
− 2
View file @ 7816a269
...@@ -12,7 +12,7 @@ Before contributing, please read and adhere to our Code of Conduct. We expect al ...@@ -12,7 +12,7 @@ Before contributing, please read and adhere to our Code of Conduct. We expect al
- Push your changes to your forked repository. - Push your changes to your forked repository.
- Submit a pull request to the original repository, explaining your changes and why they should be included. - Submit a pull request to the original repository, explaining your changes and why they should be included.
Please note that we will only accept contributions that are consistent with the project purpose and goals. Additionally, any contributions must follow the code of conduct outlined in the [`conduct.md`](conduct.md) file. Please note that we will only accept contributions that are consistent with the project purpose and goals. Additionally, any contributions must follow the code of conduct outlined in the [`conduct.md`](CODE_OF_CONDUCT.md) file.
## Bug Reports and Feature Requests ## Bug Reports and Feature Requests
If you encounter any issues or have ideas for improvements, please open an issue. Be sure to include a clear and concise description of the problem or feature request, steps to reproduce (if applicable), and any relevant screenshots or error messages. If you encounter any issues or have ideas for improvements, please open an issue. Be sure to include a clear and concise description of the problem or feature request, steps to reproduce (if applicable), and any relevant screenshots or error messages.
...@@ -26,4 +26,4 @@ By contributing to this project, you agree that your contributions will be licen ...@@ -26,4 +26,4 @@ By contributing to this project, you agree that your contributions will be licen
# Agreement # Agreement
By agreeing to this document, you agree that you will not distribute, sell, or capitalize on the project. By agreeing to this document, you agree that you will not distribute, sell, or capitalize on the project.
By contributing to the project you automatically agree to this document, By contributing to the project you automatically agree to this document,
breach of this document will be handled per `Consequences of Unacceptable Behavior` as listed in [`conduct.md`](conduct.md) breach of this document will be handled per `Consequences of Unacceptable Behavior` as listed in [`conduct.md`](CODE_OF_CONDUCT.md)
\ No newline at end of file \ No newline at end of file
Go/.env.example
+ 0
− 1
View file @ 7816a269
PORT=8080 PORT=8080
TOKEN=your_api_token
FIREBASE_CREDENTIALS_FILE=path_to_Firebase_credentials_file FIREBASE_CREDENTIALS_FILE=path_to_Firebase_credentials_file
\ No newline at end of file
LICENCE.md 0 → 100644
+ 18
− 0
View file @ 7816a269
# License
## Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International Public License
Copyright (c) 2024 [Your Full Name]
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, and share the Software in any medium or format for any non-commercial purposes, subject to the following conditions:
**Attribution** — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
**NonCommercial** — You may not use the material for commercial purposes.
**NoDerivatives** — If you remix, transform, or build upon the material, you may not distribute the modified material.
The above copyright notice and this permission notice shall be included in all copies or significant portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
README.md 0 → 100644
+ 681
− 0
View file @ 7816a269
![Text: GlobeBoard Go Rest API](go.jpg)
# GlobeBoard Go REST API
## Introduction
[![pipeline status](https://git.gvk.idi.ntnu.no/Nintendo_Alex/globeboard_cicd/badges/main/pipeline.svg)](https://git.gvk.idi.ntnu.no/Nintendo_Alex/globeboard_cicd/-/commits/main)
[![coverage report](https://git.gvk.idi.ntnu.no/Nintendo_Alex/globeboard_cicd/badges/main/coverage.svg)](https://git.gvk.idi.ntnu.no/Nintendo_Alex/globeboard_cicd/-/commits/main)
[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/license/mit/)
GlobeBoard Go REST API is a webapplication REST API service designed to provide GeoLocational Information.
## Authors
This code was developed by:
- Torgrim Thorsen [@Nintendo_Alex](https://git.gvk.idi.ntnu.no/Nintendo_Alex)
In collaboration with:
- Robin Jahre [@robinja](https://git.gvk.idi.ntnu.no/Nrobinja)
- Phrot Vedal [@BossTheModern](https://git.gvk.idi.ntnu.no/BossTheModern)
## Features
- User Registration trough Firestore Auth
- API Key Access
- GitLab CI/CD Integration
- Docker Compose Containerization
- Discord Webhook Integration
## Tech Stack
### API Implementation
- **Language:** Go
### Deployment
- **Platform:** OpenStack
- **Containerization:** Docker Compose
- **Description:** Services are containerized using Docker Compose to facilitate easy deployment and scaling.
## API Reference / Documentation
### Register as a user to retrieve API key:
```http
POST /util/v1/user/register
```
| Content-Type |
| :----------- |
| `application/x-www-form-urlencoded` |
| Key | Value: Type | Description |
|:----------|:---------|:---------------------------|
| `username` | `string` | **Required**. Your Username |
| `email` | `string` | **Required**. Your Email |
| `password` | `string` | **Required**. Your Password |
#### Response:
| Status Code | Content-Type |
|:-------------|:-------------------|
| `201 Created`| `application/json` |
```json
{
"token": "your API key"
"userid" "your Unique User ID (UUID)"
}
```
### Delete your user profile:
```http
DELETE /util/v1/user/delete/{ID}
```
| Parameter | Type | Description |
| :-------- | :------- | :---------------------- |
| `ID` | `string` | **Required**. Your UUID |
#### Response:
| Status Code | `204 No Content` |
|:------------|:-----------------|
### Delete your API key:
```http
GET /util/v1/key/
```
| Authorization | `Your UUID` |
| :------------ |:------------|
#### Response:
| Status Code | Content-Type |
|:-------------|:-------------------|
| `201 Created`| `application/json` |
```json
{
"token": "your new API key"
}
```
### Get New API key: (Old must be deleted first, only allowed one)
```http
DELETE /util/v1/key/?token={token}
```
| Parameter | Type | Description |
| :-------- | :------- | :--------------------------|
| `token` | `string` | **Required**. Your API key, to be deleted |
#### Response:
| Status Code | `204 No Content` |
|:------------|:-----------------|
### Check API Statuses: (Firestore, Dependant 3rd party API's, Version, Uptime)
```http
GET /dashboards/v1/status?token={token}
```
| Parameter | Type | Description |
| :-------- | :------- | :--------------------------|
| `token` | `string` | **Required**. Your API key |
#### Response:
| Status Code | Content-Type |
|:-------------|:-------------------|
| `200 OK` | `application/json` |
```json
{
"countries_api": "Status of the REST Countries API",
"meteo_api": "Status of the Open-Meteo API",
"currency_api": "Status of the REST Currency API",
"firebase_db": "Status of your Firestore Database",
"webhooks": "Number of webhooks tied to your user",
"version": "API Version",
"uptime": "Time since last server reboot (In Seconds)"
}
```
### Register a Country to get information for:
```http
POST /dashboards/v1/registrations?token={token}
```
| Parameter | Type | Description |
| :-------- | :------- | :--------------------------|
| `token` | `string` | **Required**. Your API key |
##### Example POST Body:
```json
{
//Name of the Country, Can be omitted if "isocode" is provided. Case-Insensitive
"country": "Norway",
//Isocode for the Country, Can be omitted if "country" is provided. Case-Insensitive
"isoCode": "NO",
// Map of Features to include when querying the dashboard endpoint,
// features to not include can be omitted
"features": {
"temperature": true,
"precipitation": true,
"capital": true,
"coordinates": true,
"population": true,
"area": true,
// List of currencies to retrieve the exchange rate for relative to local currency, NOK in this case. Case-Insensitive
"targetCurrencies": ["JPY", "usd", "EUR"]
}
}
```
#### Example of minimal allowed POST Body:
```json
{
"isocode": "us",
"features": {
"temperature": true,
"targetCurrencies": ["NOK"]
}
}
```
#### Response:
| Status Code | Content-Type |
|:-------------|:-------------------|
| `201 Created`| `application/json` |
```json
{
"id": "The registration's ID",
"lastChange": "Firestore timestamp indicating creation (RFC3339 Format)",
}
```
### Retrieve all registered countries:
```http
GET /dashboards/v1/registrations?token={token}
```
| Parameter | Type | Description |
| :-------- | :------- | :--------------------------|
| `token` | `string` | **Required**. Your API key |
#### Response:
| Status Code | Content-Type |
|:-------------|:-------------------|
| `200 OK` | `application/json` |
##### Example Response Body:
```json
[
{
"id": "4SiQmF4Vo6wyq2yW",
"country": "United States",
"isoCode": "US",
"features": {
"temperature": true,
"precipitation": false,
"capital": false,
"coordinates": false,
"population": false,
"area": false,
"targetCurrencies": [
"NOK"
]
},
"lastchange": "2024-04-18T22:21:54.105Z"
},
{
"id": "29dr0SFCfv6fyabb",
"country": "Norway",
"isoCode": "NO",
"features": {
"temperature": true,
"precipitation": true,
"capital": true,
"coordinates": true,
"population": true,
"area": true,
"targetCurrencies": [
"JPY",
"USD",
"EUR"
]
},
"lastchange": "2024-04-18T22:19:48.651Z"
}
...
]
```
### Retrieve a specific registration:
```http
GET /dashboards/v1/registrations/{ID}?token={token}
```
| Parameter | Type | Description |
| :-------- | :------- | :---------------------------------|
| `ID` | `string` | **Required**. The Registration ID |
| `token` | `string` | **Required**. Your API key |
#### Response:
| Status Code | Content-Type |
|:-------------|:-------------------|
| `200 OK` | `application/json` |
##### Example Response Body:
```json
{
"id": "4SiQmF4Vo6wyq2yW", // The Requested ID
"country": "United States",
"isoCode": "US",
"features": {
"temperature": true,
"precipitation": false,
"capital": false,
"coordinates": false,
"population": false,
"area": false,
"targetCurrencies": [
"NOK"
]
},
"lastchange": "2024-04-18T22:21:54.105Z"
}
```
### Update a specific registration:
```http
PATCH /dashboards/v1/registrations/{ID}?token={token}
```
| Parameter | Type | Description |
| :-------- | :------- | :---------------------------------|
| `ID` | `string` | **Required**. The Registration ID |
| `token` | `string` | **Required**. Your API key |
Specify features to update, Country/Isocode can not be updated,
every features is not allowed to be false, atleast one feature must be true.
##### Example POST Body:
```json
{
"features": {
"temperature": true,
"capital": true,
"coordinates": true,
"targetCurrencies": ["NOK", "EUR"]
}
}
```
#### Response:
| Status Code | Content-Type |
|:-------------|:-------------------|
|`202 Accepted`| `application/json` |
```json
{
"lastChange": "Updated Server timestamp indicating successful update"
}
```
### Delete a specific registration:
```http
DELETE /dashboards/v1/registrations/{ID}?token={token}
```
| Parameter | Type | Description |
| :-------- | :------- | :---------------------------------|
| `ID` | `string` | **Required**. The Registration ID |
| `token` | `string` | **Required**. Your API key |
#### Response:
| Status Code | `204 No Content` |
|:--------------|:-------------------|
### Retrieve a populated specific registration:
```http
GET /dashboards/v1/dashboard/{ID}?token={token}
```
| Parameter | Type | Description |
| :-------- | :------- | :---------------------------------|
| `ID` | `string` | **Required**. The Registration ID |
| `token` | `string` | **Required**. Your API key |
#### Response:
| Status Code | Content-Type |
|:---------------|:-------------------|
| `200 OK` | `application/json` |
##### Example Response Body:
```json
{
"id": "29dr0SFCfv6fyabb",
"country": "Norway",
"iso_code": "NO",
"features": {
"temperature": "-5.4",
"precipitation": "0.00",
"capital": "Oslo",
"coordinates": {
"latitude": "62.00000",
"longitude": "62.00000"
},
"population": 5379475,
"area": "323802.0",
"targetCurrencies": {
"EUR": 0.085272,
"JPY": 14.04044,
"USD": 0.090918
}
},
"lastRetrieval": "2024-04-18T23:43:04.501Z"
}
```
#### Example minimal Response Body: (Registration with only temperature)
```json
{
"id": "29dr0SFCfv6fyabb",
"country": "Norway",
"iso_code": "NO",
"features": {
"temperature": "-5.2"
},
"lastRetrieval": "2024-04-19T00:01:39.642Z"
}
```
### Register a Webhook:
```http
POST /dashboards/v1/notifications?token={token}
```
| Parameter | Type | Description |
| :-------- | :------- | :---------------------------------|
| `token` | `string` | **Required**. Your API key |
##### Example POST Body:
```json
{
"url": "Where to send the webhook payload", //Discord, webhook.site, etc...
"country": "isocode for the country the webhook applies to, leave empty for all."
"event": ["List of events the webhook applies to."]
}
```
##### List of Webhook Events:
| Event | Description |
| :---------- | :--------------------------------------|
| `INVOKE` | Envoke Webhook on retrival events. |
| `REGISTER` | Envoke Webhook on registration events. |
| `CHANGE` | Envoke Webhook on update events. |
| `DELETE` | Envoke Webhook on deletion events. |
#### Response:
| Status Code | Content-Type |
|:---------------|:-------------------|
| `201 Created` | `application/json` |
##### Example Response Body:
```json
{
"id": "Webhook ID"
}
```
### Retrieve all Webhooks:
```http
GET /dashboards/v1/notifications?token={token}
```
| Parameter | Type | Description |
| :-------- | :------- | :---------------------------------|
| `token` | `string` | **Required**. Your API key |
#### Response:
| Status Code | Content-Type |
|:---------------|:-------------------|
| `200 OK` | `application/json` |
##### Example Response Body:
```json
[
{
"id": "J0Y5k6KCuRpPKC8n",
"url": "https://discord.com/api/webhooks",
"event": [
"INVOKE",
"REGISTER",
"CHANGE",
"DELETE"
]
},
{
"id": "FfbtRI0kEcRVus3D",
"url": "https://webhook.site/",
"country": "NO",
"event": [
"INVOKE"
]
}
]
```
### Retrieve specific Webhook:
```http
GET /dashboards/v1/notifications/{ID}?token={token}
```
| Parameter | Type | Description |
| :-------- | :------- | :----------------------------|
| `ID` | `string` | **Required**. The Webhook ID |
| `token` | `string` | **Required**. Your API key |
#### Response:
| Status Code | Content-Type |
|:---------------|:-------------------|
| `200 OK` | `application/json` |
##### Example Response Body:
```json
{
"id": "FfbtRI0kEcRVus3D",
"url": "https://webhook.site/",
"country": "NO",
"event": [
"INVOKE"
]
}
```
### Delete a Webhook:
```http
DELETE /dashboards/v1/notifications/{ID}?token={token}
```
| Parameter | Type | Description |
| :-------- | :------- | :----------------------------|
| `ID` | `string` | **Required**. The Webhook ID |
| `token` | `string` | **Required**. Your API key |
#### Response:
| Status Code | `204 No Content` |
|:--------------|:-------------------|
## Environment Variables
To run this project, you will need to add the following environment variables to your .env file, or project environment.
`PORT` - Port to run project on.
`FIREBASE_CREDENTIALS_FILE` - Path to your Firebase credentials file.
## Run Locally
- Clone the repository
```bash
git clone git@git.gvk.idi.ntnu.no:course/prog2005/prog2005-2024-workspace/nintendo_alex/globeboard.git
```
- Navigate to the project directory:
```bash
cd globeboard/Go/
```
- ### Run using Go:
```bash
go run ./cmd/globeboard/app.go
```
- From Build:
```bash
go build -a -o app ./cmd/globeboard
```
```bash
./app
```
- ### Run using Docker:
```bash
docker compose build
```
- #### Attached - Command line remains connected:
```bash
docker compose up globeboard
```
- #### Detached - Start the container in the background:
```bash
docker compose up globeboard -d
```
- #### View Logs:
```bash
docker compose logs globeboard
```
- #### Follow Logs:
```bash
docker compose logs globeboard -f
```
- #### Stop Services:
```bash
docker compose down globeboard
```
## Running Tests
To run tests, navigate to the project directory:
```bash
cd globeboard/Go/
```
- ### Run test using Go:
```bash
go test ./cmd/globeboard
```
- From Build:
```bash
go test -c -o test ./cmd/globeboard
```
```bash
./app
```
- With Coverage using Go: (Full Project)
```bash
go test -cover -coverpkg=./... ./cmd/globeboar
```
- With Coverage from Build:
```bash
go test -c -cover -coverpkg=./... -o test ./cmd/globeboard
```
```bash
./test
```
- ### Run test in Docker:
```bash
docker compose build
```
- #### Attached - Command line remains connected:
```bash
docker compose up globeboard-test
```
- #### Detached - Start the container in the background:
```bash
docker compose up globeboard-test -d
```
- #### View Logs:
```bash
docker compose logs globeboard-test
```
- #### Follow Logs:
```bash
docker compose logs globeboard-test -f
```
- #### Stop Services:
```bash
docker compose down globeboard-test
```
## Contributing
Contributions to the GlobeBoard REST API are welcome! To contribute, follow these steps:
- Fork the repository.
- Clone your forked repository to your local machine.
- Create a new branch for your changes.
- Make your changes and commit them with clear and concise messages.
- Push your changes to your forked repository.
- Submit a pull request to the original repository, explaining your changes and their significance.
Please adhere to the project's code of conduct and contribution guidelines provided in the [`./CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) and [`./CONTRIBUTING.md`](CONTRIBUTING.md) files, respectively.
## Support
For support, email `torgrilt@stud.ntnu.no` or `torgrim.l.thorsen@gmail.com`.
## License
This project is licensed under:
[![License: CC BY-NC-ND 4.0](https://img.shields.io/badge/License-CC_BY--NC--ND_4.0-green.svg)](https://creativecommons.org/licenses/by-nc-nd/4.0/)
You are free to download and use this code for educational, personal learning, or non-commercial purposes. And while we encourage these uses, please note that utilizing this project for commercial distribution, sales, or any form of monetization is not permitted.
\ No newline at end of file
readme.md deleted 100644 → 0
+ 0
− 113
View file @ da9767a1
# GlobeBoard Go REST API
![Text: GlobeBoard Go Rest API](./readme/go.jpg)
## Introduction
[![pipeline status](https://git.gvk.idi.ntnu.no/Nintendo_Alex/globeboard_cicd/badges/main/pipeline.svg)](https://git.gvk.idi.ntnu.no/Nintendo_Alex/globeboard_cicd/-/commits/main)
[![coverage report](https://git.gvk.idi.ntnu.no/Nintendo_Alex/globeboard_cicd/badges/main/coverage.svg)](https://git.gvk.idi.ntnu.no/Nintendo_Alex/globeboard_cicd/-/commits/main)
[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/license/mit/)
GlobeBoard Go REST API is a webapplication REST API service designed to provide GeoLocational Information.
## Author
This code was developed by:
- Torgrim Thorsen [@Nintendo_Alex](https://git.gvk.idi.ntnu.no/Nintendo_Alex)
- Robin Jahre [@robinja](https://git.gvk.idi.ntnu.no/Nrobinja)
- Phrot Vedal [@BossTheModern](https://git.gvk.idi.ntnu.no/BossTheModern)
## Features
- TODO
## Endpoints
### Library
- **Endpoint**: `/library/v1/?languages={:two_letter_language_code+}{&search={:string}}{&page={:number}}`
- **Method**: GET
- **Description**: This endpoint provides access to the Gutendex library, allowing users to retrieve various information about books and their metadata. Users can specify parameters to filter the results:
- `languages`: Optional parameter to filter books by language. Users can specify one or more two-letter language codes.
- `search`: Optional parameter to search for books based on a provided string.
- `page`: Optional parameter to paginate through the results, specifying the page number.
Example:
```
/library/v1/?languages=en,fr&search=charles&page=1
```
This endpoint enables users to query the Gutendex library and retrieve relevant book information based on their criteria.
### Supported Languages
- **Endpoint**: `/librarystats/v1/supported_languages/`
- **Method**: GET
- **Description**: This endpoint returns a list of supported languages for the Gutendex library.
### Book Count
- **Endpoint**: `/librarystats/v1/bookcount/?languages={:two_letter_language_code+}/`
- **Method**: GET
- **Description**: This endpoint allows users to retrieve the count of books, authors, and pages available in the Gutendex library for the specified languages.
- **Parameters**:
- `languages`: (Required) Specifies the languages for which book count is requested. It accepts one or more two-letter language codes.
- **Example**:
```
/librarystats/v1/bookcount/?languages=en,fr
```
### Readership
- **Endpoint**: `/librarystats/v1/readership/{:two_letter_language_code}/{?limit={:number}}`
- **Description**: This endpoint retrieves statistics related to readership, such as the number of possible readers for the Gutendex library from countries for a specified language.
- **Parameters**:
- `language_code`: (Required) Specifies the language for which readership statistics are requested.
- `limit`: (Optional) Limits the number of results returned. Defaults to all readership statistics if not provided.
- **Example**:
```
/librarystats/v1/readership/en/?limit=10
```
### Status
- **Endpoint**: `/librarystats/v1/status/`
- **Method**: GET
- **Description**: This endpoint returns the current status of the Gutendex library, providing information about the uptime, version number, and the status of the APIs Gutendex is communicating with. Users can use this endpoint to monitor the availability and operational status of the Gutendex service.
These endpoints enable users to interact with the Gutendex REST API, accessing various functionalities and retrieving relevant data.
## Setup
To Run Gutendex REST API locally, follow these steps:
1. Clone the repository:
```bash
git clone https://git.gvk.idi.ntnu.no/course/prog2005/prog2005-2024-workspace/nintendo_alex/globeboard.git
```
2. Navigate to the project directory:
```bash
cd GlobeBoard/Go/cmd/globeboard
```
3. Run the Go server:
```bash
go run app.go
```
4. Access the REST API endpoints through your preferred HTTP client.
## Roadmap
- TODO
## Contributing
Contributions to the GlobeBoard REST API are welcome! To contribute, follow these steps:
1. Fork the repository.
2. Clone your forked repository to your local machine.
3. Create a new branch for your changes.
4. Make your changes and commit them with clear and concise messages.
5. Push your changes to your forked repository.
6. Submit a pull request to the original repository, explaining your changes and their significance.
Please adhere to the project's code of conduct and contribution guidelines provided in the [`./readme/conduct.md`](./readme/conduct.md) and [`./readme/contribute.md`](./readme/contribute.md) files, respectively.
## License
This project is licensed under:
[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/license/mit/)
You are free to download and use the code for academic or non-commercial purposes, but distribution, selling, or capitalizing on the project is strictly prohibited.
\ No newline at end of file
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment