From 986bce1a948d9c1dabf466c9af6eae6510d4d850 Mon Sep 17 00:00:00 2001 From: Danial Raza Date: Thu, 18 Jan 2024 00:57:58 +0100 Subject: [PATCH] chore: introduce documentation and project files (#8) --- .github/CODE_OF_CONDUCT.md | 60 +++++++++++++++++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 1 + README.md | 51 +++++++++++++++++++++++ docs/info/get-api-information.md | 26 ++++++++++++ docs/quotes/create-quote.md | 54 ++++++++++++++++++++++++ docs/quotes/get-quote-by-id.md | 28 +++++++++++++ docs/quotes/get-quotes-by-author.md | 40 ++++++++++++++++++ docs/quotes/get-quotes-in-category.md | 30 ++++++++++++++ docs/quotes/get-quotes.md | 40 ++++++++++++++++++ docs/quotes/get-random-quote.md | 28 +++++++++++++ 10 files changed, 358 insertions(+) create mode 100644 .github/CODE_OF_CONDUCT.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 README.md create mode 100644 docs/info/get-api-information.md create mode 100644 docs/quotes/create-quote.md create mode 100644 docs/quotes/get-quote-by-id.md create mode 100644 docs/quotes/get-quotes-by-author.md create mode 100644 docs/quotes/get-quotes-in-category.md create mode 100644 docs/quotes/get-quotes.md create mode 100644 docs/quotes/get-random-quote.md diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..0f07d10 --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,60 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, race, +religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +- The use of sexualized language or imagery and unwelcome sexual attention or + advances +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic + address, without explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..a0d7a9f --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1 @@ +**Please describe the changes this PR makes and why it should be merged:** diff --git a/README.md b/README.md new file mode 100644 index 0000000..38c138b --- /dev/null +++ b/README.md @@ -0,0 +1,51 @@ +# 📝 Quote It + +[![CI Tests](https://github.com/sdanialraza/quote-it/actions/workflows/tests.yml/badge.svg)](https://github.com/sdanialraza/quote-it/actions/workflows/tests.yml) + +**Quote It** is a simple but powerful REST API that provides a collection of funny, inspirational, motivational, and thought-providing quotes. You can also create your own quotes, check out the create quote documentation [here](docs/quotes/create-quote.md). + +### 🖥️ Base URL + +``` +https://quoteit.sdanialraza.dev +``` + +## 🔧 Usage + +For detailed information on how to use each endpoint, refer to the corresponding documentation linked below. + +## 🛣️ Endpoints + +- [Get API information](docs/info/get-api-information.md) + +### + +- [Get All Quotes](docs/quotes/get-quotes.md) +- [Get Random Quote](docs/quotes/get-random-quote.md) +- [Get Quote By Id](docs/quotes/get-quote-by-id.md) +- [Get all the quotes by an author](docs/quotes/get-quotes-by-author.md) +- [Get all the quotes in a category](docs/quotes/get-quotes-in-category.md) +- [Create a quote](docs/quotes/create-quote) + +## Quote Structure + +| Field | Type | Description | +| ---------- | ----------------- | ----------------------------------- | +| id | integer | The id of the quote | +| created_at | ISO8601 timestamp | The date the quote was submitted | +| updated_at | ISO8601 timestamp | The date the quote was last updated | +| author | string | The author of the quote | +| categories | array of string | The categories the quote belongs in | +| submitter | string | The submitter of the quote | +| text | string | The text content of the quote | +| verified\* | boolean | Whether the quote is verified | + +\* To make sure the quotes don't contain any offensive content, all quotes are verified manually and only verified quotes are returned by the API. + +## 🤝 Contributing + +Pull request are welcome, and very much appreciated. But before you start working on a pull request, please make sure to open an issue first, so that we can discuss the changes you want to make. + +## ⚖️ License + +This project is licensed under the [MIT License](LICENSE). diff --git a/docs/info/get-api-information.md b/docs/info/get-api-information.md new file mode 100644 index 0000000..5b82df5 --- /dev/null +++ b/docs/info/get-api-information.md @@ -0,0 +1,26 @@ +# Get API Information + +Get information about the API. Returns an object containing information about the API on success. + +## Endpoint + +```http +GET /info +``` + +## Parameters + +No specific parameters are required for this endpoint. + +## Example Response + +```json +{ + "name": "Quote-It", + "description": "Your go-to API for inspiring, and thought-provoking quotes.", + "version": "1.0.0", + "counts": { + "quotes": 51 + } +} +``` diff --git a/docs/quotes/create-quote.md b/docs/quotes/create-quote.md new file mode 100644 index 0000000..a1b4164 --- /dev/null +++ b/docs/quotes/create-quote.md @@ -0,0 +1,54 @@ +# Create Quote + +Create a quote in the Quote It API. Returns a [quote object](../../README.md#quote-structure) on success. + +## Endpoint + +```http +POST /quotes +``` + +## Request Body + +The request body takes the following JSON format: + +| Field | Type | Description | +| ---------- | --------------- | ----------------------------------------------------- | +| author\* | ?string | The author of the quote (1-30 characters) | +| categories | array of string | The categories the quote belongs in (1-20 characters) | +| submitter | string | The submitter of the quote (1-20 characters) | +| text | string | The text content of the quote (1-200 characters) | + +\* The author field is optional. If it is not provided, the author will be set to "Unknown". + +## Example Request Body + +```json +{ + "quote": { + "author": "Steve Jobs", + "categories": ["Work"], + "submitter": "sdanialraza", + "text": "The only way to do great work is to love what you do." + } +} +``` + +## Example Response Body + +```json +{ + "quote": { + "author": "Steve Jobs", + "createdAt": "2024-01-17T23:02:53.795Z", + "updatedAt": "2024-01-17T23:02:53.795Z", + "categories": ["Work"], + "id": 1, + "submitter": "sdanialraza", + "text": "The only way to do great work is to love what you do.", + "verified": false + } +} +``` + +`verified` property will always be false for newly created quotes. More information on verification can be found [here](../../README.md#quote-structure). diff --git a/docs/quotes/get-quote-by-id.md b/docs/quotes/get-quote-by-id.md new file mode 100644 index 0000000..20e8e2d --- /dev/null +++ b/docs/quotes/get-quote-by-id.md @@ -0,0 +1,28 @@ +# Get Quote By Id + +Get a quote by its id. Returns a single [quote object](../../README.md#quote-structure) on success. + +## Endpoint + +```http +GET /quotes/:id +``` + +## Parameters + +- **id** - The id of the quote. + +### Example Response + +```json +{ + "id": 19, + "createdAt": "2024-01-13T02:35:52.222Z", + "updatedAt": "2024-01-13T02:35:52.222Z", + "author": "Napoleon Hill", + "categories": ["Motivational"], + "submitter": "sdanialraza", + "text": "The starting point of all achievement is desire.", + "verified": true +} +``` diff --git a/docs/quotes/get-quotes-by-author.md b/docs/quotes/get-quotes-by-author.md new file mode 100644 index 0000000..8dc0201 --- /dev/null +++ b/docs/quotes/get-quotes-by-author.md @@ -0,0 +1,40 @@ +# Get Quotes By Author + +Get all quotes by a specific author. Returns an array of [quote objects](../../README.md#quote-structure) on success. + +## Endpoint + +```http +GET /quotes/author/:author +``` + +## Parameters + +- **author** - The name of the author. + +### Example Response + +```json +[ + { + "id": 16, + "createdAt": "2024-01-13T02:35:52.213Z", + "updatedAt": "2024-01-13T02:35:52.213Z", + "author": "Winston Churchill", + "categories": ["Motivational"], + "submitter": "sdanialraza", + "text": "Success is not final, failure is not fatal: It is the courage to continue that counts.", + "verified": true + }, + { + "id": 39, + "createdAt": "2024-01-13T02:35:52.286Z", + "updatedAt": "2024-01-13T02:35:52.286Z", + "author": "Winston Churchill", + "categories": ["Wisdom"], + "submitter": "sdanialraza", + "text": "Success consists of going from failure to failure without loss of enthusiasm.", + "verified": true + } +] +``` diff --git a/docs/quotes/get-quotes-in-category.md b/docs/quotes/get-quotes-in-category.md new file mode 100644 index 0000000..ed0272e --- /dev/null +++ b/docs/quotes/get-quotes-in-category.md @@ -0,0 +1,30 @@ +# Get Quotes In Category + +Get all quotes in a specific category. Returns an array of [quote objects](../../README.md#quote-structure) on success. + +## Endpoint + +```http +GET /quotes/category/:category +``` + +## Parameters + +- **category** - The name of the category. + +## Example Response + +```json +[ + { + "id": 4, + "createdAt": "2024-01-13T02:35:52.173Z", + "updatedAt": "2024-01-13T02:35:52.173Z", + "author": "Eleanor Roosevelt", + "categories": ["People"], + "submitter": "sdanialraza", + "text": "Great minds discuss ideas; average minds discuss events; small minds discuss people.", + "verified": true + } +] +``` diff --git a/docs/quotes/get-quotes.md b/docs/quotes/get-quotes.md new file mode 100644 index 0000000..f2bc02b --- /dev/null +++ b/docs/quotes/get-quotes.md @@ -0,0 +1,40 @@ +# Get All Quotes + +Get all quotes. Returns an array of [quote objects](../../README.md#quote-structure) on success. + +## Endpoint + +```http +GET /quotes +``` + +## Parameters + +No specific parameters are required for this endpoint. + +## Example Response + +```json +[ + { + "id": 1, + "createdAt": "2024-01-13T02:35:52.159Z", + "updatedAt": "2024-01-13T02:35:52.159Z", + "author": "Steve Jobs", + "categories": ["Work"], + "submitter": "sdanialraza", + "text": "The only way to do great work is to love what you do.", + "verified": true + }, + { + "id": 2, + "createdAt": "2024-01-13T02:35:52.166Z", + "updatedAt": "2024-01-13T02:35:52.166Z", + "author": "Nelson Mandela", + "categories": ["Life"], + "submitter": "sdanialraza", + "text": "The greatest glory in living lies not in never falling, but in rising every time we fall.", + "verified": true + } +] +``` diff --git a/docs/quotes/get-random-quote.md b/docs/quotes/get-random-quote.md new file mode 100644 index 0000000..691d52b --- /dev/null +++ b/docs/quotes/get-random-quote.md @@ -0,0 +1,28 @@ +# Get Random Quote + +Get a random quote. Returns a single [quote object](../../README.md#quote-structure) on success. + +## Endpoint + +```http +GET /quotes/random +``` + +## Parameters + +No specific parameters are required for this endpoint. + +## Example Response + +```json +{ + "id": 21, + "createdAt": "2024-01-13T02:35:52.228Z", + "updatedAt": "2024-01-13T02:35:52.228Z", + "author": "Martin Luther King Jr.", + "categories": ["Inspirational"], + "submitter": "sdanialraza", + "text": "Darkness cannot drive out darkness; only light can do that. Hate cannot drive out hate; only love can do that.", + "verified": true +} +```