wh-iterabb-it/meowfacts

🐈 a simple api which returns a catfact

meowfacts

Description:

A simple api that returns a random fact about cats on a GET request

Example Usage

curl https://meowfacts.herokuapp.com/

Response

{
  "data": [
    "0": 	"Mother cats teach their kittens to use the litter box."
  ]
}

Advanced Usage

You can request more than one fact at a time by using the GET param count

curl https://meowfacts.herokuapp.com/?count=3

Response

{
  "data": [
    "0": 	"Mother cats teach their kittens to use the litter box.",
    "1": "A cat can sprint at about thirty-one miles per hour.",
    "2": "The worlds richest cat is worth $13 million after his human passed away and left her fortune to him."
  ]
}

You can request a specific fact if you know the ID / order it is buy passing the GET param id

curl https://meowfacts.herokuapp.com/?id=3

Response

{
  "data": [
    "0": 	"Mother cats teach their kittens to use the litter box."
  ]
}

Language Support

You can request the response in different languages by using the GET param lang

curl https://meowfacts.herokuapp.com/?lang=ukr

Response

{
  "data": [
    "0": 	"Найбагатший у світі кіт коштує 13 мільйонів доларів після того, як його людина померла і залишила йому свій стан"
  ]
}

Supported Languages

The supported languages are listed below, you can use any of the lang Values in the first column as a lang param.

"?lang=esp" and "?lang=esp-mx" will both return spanish for your response, and simply using the ISO-639-1 code will default to esp-mx for simplicity.

LANG Variable	ISO 639-1	Language Name	Localization (country)
eng-us	eng	English	USA
ces-cz or cze-cz	cze (B) ces (T)	Czech	CZ
ger-de	ger	German	DE
ben-in	ben	Bengali	IN
esp-es	esp	Spanish	ES
esp-mx	esp	Spanish (default)	MX
rus-ru	rus	Russian	RUS
por-br	por	Portuguese	BR
tl-fil	fil	Filipino	PH
ukr-ua	ukr	Ukrainian	UA
urd-ur	urd	Urdu	UR
ita-it	ita	Italian	IT
zho-tw	zho	Chinese	TW (Taiwan)
kor-ko	kor	Korean	KO

Help us expand and improve Internationalization on this API (Click to expand)

Help us expand and improve Internationalization on this API

Note: We are trying to follow the browser's language tags, which are formally defined in RFC 5646, which rely on the ISO 639 standard (quite often the 639-1 code list) for language codes to be used.

We would love it if you helped this project by taking a look at our Call for Contributors to see if you can make a contribution that helps us be more inclusive and support more languages.

Documentation

Local Development

Installation

npm install

Basic usage

npm run start

Dedication && Funding

This api is dedicated to pistachio; she brought me great comfort in dire times. Words can't describe the debt I owe to her.

If you enjoy this api, or just love cats, please donate to:

NYC Animal Project Website

NYC Animal Project Paypal Link

NYC Animal Project is a struggling `no kill` cat shelter in the heart of new york that relies entirely on fosters and help from small donations. I can say personally having volunteered for them, even a few cents donation would make a difference for the very small organization. I fostered many kittens from them, and Pistachio was the runt that went un-adopted. She was shy, but very outgoing when she got settled. I highly recommend to foster and adopt if you can.

meowfacts's Issues

[i18n] Urdu (Pakistan)

Call for Translator Help

Facts needed Translating in Urdu (Pakistan) Localization

Please make any PR that adds additional translated facts to the file.

Main Issue: #175

Translate cat facts to Urdu (Pakistan)

Tutorial for client side usage

Description of changes

Ideally we can have some examples using the api with different clients. Having a separate markdown page in ./docs/ at least outlining front-end requests is a great learning resource and helps get people started. I also like a lot of the other tutorials in the wild, and would love to have our own we update a bit.

Objectives

• Demonstrate different ways to use the API with examples
• a basic react example that does an HTTP GET` request to the API.
• (future/optional) add on different ways the query params are used like count and lang

Create Issue Template for easier contributions

Add Back Query Param `count` to endpoint

Implement the previously used count query param to allow multiple facts in a response.

Called out in issue:
#98

modernize repo

The repo has been neglected for a bit, and some best practices can easily be implemented to the repo to make it better.

These are mostly security-related updates, refactoring to get rid of technical debt and make future feature/fixes easier.

Requirements

• a snyk.io integration, CI/CD check / badge
• a LGTM.com integration, CI/CD check / badge
• update any dependencies and update CI/CD versions
• rename master -> main and automation that goes with that
• update the travis file and convert it to some sort of github action that uses the docker container
• update the despertly out of date docker container

📚 Create Interactive webpage for API Documentation and Implementation Guide

📖 Overview

To enhance the usability and adoption of our backend API, we need to create an interactive documentation page that guides new users on how to implement the API effectively. This documentation will serve as a comprehensive resource for developers, providing step-by-step instructions, examples, and detailed explanations.

🚀 Proposed Solution

I propose building a dedicated web page within our project repository that will host the API documentation and implementation guide. This page will be designed using modern web technologies and will provide a user-friendly experience to developers, regardless of their experience level. The documentation will be presented in a clear and concise manner, making it easy for new users to understand and implement our API.

📝 Key Features

The following key features are suggested for the interactive documentation page:

1. Introduction and Getting Started: An overview of the API's purpose, its capabilities, and a guide on how to get started using it.

2. Endpoints and Parameters: A detailed listing of all available endpoints, along with their associated parameters and expected responses.

3. Authentication and Authorization: Guidance on how to authenticate requests and obtain necessary access tokens or API keys.

4. Code Examples: Practical code snippets demonstrating how to use the API in various programming languages, making it easier for developers to integrate it into their projects.

5. Error Handling: Information on error responses, common troubleshooting tips, and best practices for handling errors gracefully.

6. FAQs and Troubleshooting: A section that addresses frequently asked questions and common issues developers may encounter while implementing the API.

Please feel free to ask any questions or suggest additional features that would enhance the usability and effectiveness of our API documentation. Let's work together to make our API implementation guide a valuable resource for all developers!

[i18n] Translate to Nepali.

translate cat facts to Nepali (np).

[Request] Use RFC 5646 for README and folders name.

I think the standardized nomenclature for languages is not accurate in the README.

The column table "ISO 639-1" is not exactly the wikipedia description of "two-letter codes"

And this section says that you intend to use RFC 5646 but is different from this list

Request: Use RFC 5646 for README and folders name.

[BUG] Unnecessary exposing of Ports in Dockerfile

In the Dockerfile, the ports exposed are from range 3000-5001 whereas the application only uses port 5000

Even though it does not creates any major difference, It can create unnecessary confusion to anyone who is reading the Dockerfile for Reference

[i18n] Español ES

Call for Translator Help

Facts needed Translating in Spanish ES Localization esp-es

Please make any PR that adds additional translated facts to the file.

Main Issue: #175

Barrelling and Factory for Languages

First outlined by @nickcrisci in a very well-thought-out and great contribution PR #206

I wanted to define a little bit how this change works and outline some of its improvements in an issue.

What this does

• makes it so all you need is to create the new src/models/localization/ with some additional fields, and no longer need to edit /middleware or other files to configure accepting the new languages.
• the accepted languages update based on the files in the folder, allowing quicker contributions and ease of development.

How this is done

[TO-DO] @BeauBouchard CC @switchhalt [fill this part out in more detail]

We want to adhere to the Standards for Content-Language and Accept-Language going forward.

Note: Language tags are formally defined in RFC 5646, which rely on the ISO 639 standard (quite often the ISO 639-1 code list) for language codes to be used.

Adds a short configurable field at the top of the facts file which specifies our agreed on conventions for querying it in the I18N codes we use.

In this example, we add a new language file for Canadian English.

It would be src/models/localization/eng-ca.js and look like

const facts = [
  "Cats have been the most popular pet for families in Canada since data was first collected in 1987.",
  "..."
];

const langName = "English", // normally this is the language name
  langISO = "eng", 
  langLocale = "ca", 
  langLocaleName = "Canadian"; 

module.exports = {
  langName,
  langISO,
  langLocale,
  langLocaleName,
  code: `${langISO}-${langLocale}`,
  codeName: `${langName} (${langLocaleName})`,
  facts: facts,
};

If you query the api with eng-ca language parameter you will get the facts appearing more for the tailored localization in the language of english.

Feel free to change the facts to be more meaningful to the location you want, as the original english facts are with america in mind, I would love to see what other places have for accurate and high quality facts about cats.

Work

• merge this PR after it is passed which completes the majority of the work for this endeavor #208
• add additional documentation to the existing localization issue here #175
• add additional documentation to the README.md listing the languages
• create a new issue to demonstrate how a new language could be added, as well as making a few other issues more concise and specific for their contributions with less additional work in middleware/routing.

[i18n] Traditional South Korea 'kor-ko' translation

Call for Translator Help

Facts needed Translating in

Acceptance Criteria

• Create a new file ./src/models/localizations/kor-ko.js
• Using the Template below, translate existing and even add new cat facts in the localized language.

Template

const facts = [
  "..."
];

const langName = "Korean", // normally this is the language name
  langISO = "kor", 
  langLocale = "ko", 
  langLocaleName = "Korean"; 

module.exports = {
  langName,
  langISO,
  langLocale,
  langLocaleName,
  code: `${langISO}-${langLocale}`,
  codeName: `${langName} (${langLocaleName})`,
  facts: facts,
};

Inspired by #175 (comment) from Main Issue: #175

[i18n] Portuguese (Brazil)

Call for Translator Help

Facts needed Translating in Portuguese (Brazil) Localization

Please make any PR that adds additional translated facts to the file.

Main Issue: #175

Translate 90 cat facts to Portuguese

[i18n] Italian 'ita-it' translation

Call for Translator Help

Minimal requirements

• Create a new file named ita-it.js in the src/models/localization/ folder
• use the template below to get started, but translate some other cat facts from the other file into that file
• make a PR and mention this Issue in the description.

Starting Template Example

const facts = [
  "a single fact per a line :D",
  "..."
];

const langName = "Italian",
  langISO = "ita",
  langLocale = "it",
  langLocaleName = "Italy";

module.exports = {
  langName,
  langISO,
  langLocale,
  langLocaleName,
  code: `${langISO}-${langLocale}`,
  codeName: `${langName} (${langLocaleName})`,
  facts: facts,
};

Feel free to change the facts to be more meaningful to the location you want, as the original English facts are with America in mind, I would love to see what other places have for accurate and high-quality facts about cats.

English name of Language: Italian
ISO 639-2/BT Language Code: ita
Language Dialect Local: Italy

Please make any PR that adds additional translated facts to the file.

Note: Please forgive me if I use language or terminology incorrectly, please do correct me and we will all learn together how things are expressed differently in other places.

Main Issue: #175

Count parameter not working

I tried the url to get more than one cat fact but it is not working ie curl https://meowfacts.herokuapp.com/?count=3.

Returning Undefined

Hey guys, I'm trying to make an app in React Native that returns the cats facts, with axios, but it keeps returning undefined, can somebody help me with this?

[BUG] Fix Prettier to update

Bumps prettier from 2.8.8 to 3.0.3.

sst

Description of Problem

we can no longer npm install correctly without github access credentials for the sst repo (?)(unsure)

Causes

recently sst and i think a dep from it made it so it can't be installed.

This causes development to break noted in #194

Solution and Mitigation

We need to refactor a few functions out of SST or fix SST https://github.com/wh-iterabb-it/sst which hasn't had its issue identified yet.

Want to add Bengali language

I know bengali very well so I want to add bengali language support to this api.

Does it have any contribution docs to guide me how to add a new language support ?

Add a contribution guide.

[i18n] Español MX

Call for Translator Help

Facts needed Translating in Spanish MX Localization esp-mx

Please make any PR that adds additional translated facts to the file.

Main Issue: #175

[i18n] Hindi 'hin-in' translation

Main Issue: #175

Translate 90 cat facts to Hindi

Security Fixes

found 17 vulnerabilities (1 moderate, 15 high, 1 critical)

being honest about the integrations with the other services found a lot of things that need fixing...

[chore] Readd CodeCov

Previously we let codecoverage reporting from codecov to continue to be disabled after the previous issues they had a few years ago.
Overall I would like to have a codecoverage service still, and due to the public nature of this codebase, we want to re-enable this service and repair its integration.

Tasks

• Add a step to the CI/CD on Push workflow
• Add coverage badge to README.md
• (optional) add necessary tests if there is missing coverage

update docker image

Description

I am thinking about changing the docker image from node:14 to something a lot smaller, i used to alpine back in the day, but am aware there are some better ones now.

• Updates docker image to 14-alpine

is count query parameter not working?

https://meowfacts.herokuapp.com/?count=4 only returns a single fact still? perhaps I am using it wrong?

[i18n] Tagalog (Filipino)

Call for Translator Help

Facts needed Translating in Tagalog (Filipino) Localization

Please make any PR that adds additional translated facts to the file.

Main Issue: #175

Translate cat facts to Tagalog (Filipino)

Fix languages returned in error message

Description

return the whole language list in the 400 error the middleware serves when requesting with the wrong language.

See this line: https://github.com/wh-iterabb-it/meowfacts/blob/main/src/middleware.js#L56

shortISO.join(", ") should be VALID_LANGUAGES.join(", ") as that is what is being checked against above in validateLanguage function, and the correct way we should respond.

Objectives to fix

• Fix https://github.com/wh-iterabb-it/meowfacts/blob/main/src/middleware.js#L56 line
• Remove this console.log https://github.com/wh-iterabb-it/meowfacts/blob/main/src/middleware.js#L4

[i18n] Bengali 'ben-in' translation #304

Call for Translator Help

Facts needed Translating in Bengali for India location

Acceptance Criteria

• Create a new file ./src/models/localizations/ben-in.js
• Using the Template below, translate existing and even add new cat facts in the localized language.

Template

const facts = [
  "..."
];

const langName = "bengali",
	langISO = "ben",
	langLocale = "in",
	langLocaleName = "India";

module.exports = {
	langName,
	langISO,
	langLocale,
	langLocaleName,
	code: `${langISO}-${langLocale}`,
	codeName: `${langName} (${langLocaleName})`,
	facts: facts,
};

Inspired by #318 from Main Issue: #175

[chore] Update Documentation for OpenAPI 3

Description

I want to convert the existing YAML to a JSON file, and use that going forward from our repo.

Tasks

• Document /health endpoint
• Document /options endpoint
• Refactor YAML to JSON

Help Translating 3 facts into Ukrainian and Russian facts

Big thanks to amiarham who added 3 facts to eng-US.js in #183 .

We now need to translate these 3 facts into the other 2 locals to make sure we are having the same experience for all languages we support.

  "Cats can jump up to six times their length.",
  "Cats have contributed to the extinction of 33 different species.",
  "Cats can drink sea water in order to survive.",

Acceptance Criteria

• Translate the above 3 facts to Ukrainian in ukr-UA.js completed in #188
• Translate the above 3 facts to Russian in rus-RU.js completed in #187

[I18N] Looking for Help With Translation

Call for Translators

While trying to translate I learned a lot and direct translations may not be the most accurate. I am always looking for suggestions and help in this regard and let this issue stand as a call for maintainers or contributors who want to improve the translation or even help make the API available in different languages.

Translation Issues that could use your Help

• #210
• #209
• #255
• #211
• #304
• We welcome all other languages to be included. If you plan to or want to make a contribution, its recommended you make an issue first, and we will help you get started :D

Everything Explained

I18N means Internationalization with 18 letters between I and N, its often abbreviated. Supporting languages isn't always easy, as languages often have regional dialects which is why they created the word localization. This is mapping the language to a location, an easy example of this is thinking of french in Canada or France, Spanish in Mexico vs Spain, or American English vs England's English.

We want to adhere to the Standards for Content-Language and Accept-Language going forward.

Note: Language tags are formally defined in RFC 5646, which rely on the ISO 639 standard (quite often the ISO 639-1 code list) for language codes to be used.

FAQ

Example of how to make a new Language

In this example, we add a new language file for Canadian English.

We only need to make a single file, It would be src/models/localization/eng-ca.js and look like

const facts = [
  "Cats have been the most popular pet for families in Canada since data was first collected in 1987.",
  "..."
];

const langName = "English", // normally this is the language name
  langISO = "eng", 
  langLocale = "ca", 
  langLocaleName = "Canadian"; 

module.exports = {
  langName,
  langISO,
  langLocale,
  langLocaleName,
  code: `${langISO}-${langLocale}`,
  codeName: `${langName} (${langLocaleName})`,
  facts: facts,
};

If you query the api with eng-ca language parameter you will get the facts appearing more for the tailored localization in the language of english.

Feel free to change the facts to be more meaningful to the location you want, as the original English facts are with America in mind, I would love to see what other places have for accurate and high-quality facts about cats.

:D Looking forward to all contributions

[bug] Fix default language for multi-language locales

Querying esp has 2 files it can go to in ./src/models/localizations folder, we wanted originally to one to be the default, if the short code is used for the request.

Example of bug:

User is querying the endpoint with ?lang=esp

We want to control the default behavior to go to the esp-es or esp-mx response.

Please edit one of the facts

I looked at the facts list, and the word cat in the indonesian language mentioned is wrong. Instead of "qitta", it should be "kucing", the same as Malay.

create contributing COC document

We want to have a copy of the COC and Contributing pages appear in all readmes from links. we can consolidate those to a single org repo, or put them in the /docs/ of the repos.

Referencing another organization, free-ignorance/fortunecookie#163 where we are trying to uniformly adopt a COC.

I think we did it previously in /shrewd/ but I am very open to doing it differently if we are going to have the same policy for all public repos.

Acceptence Crtieria

• Link to COC in README of repo
  • We previously used the Contributor Covenant Homepage, version v1.4.0 as hosted in the /shrewd/ repo.
• Link to Contributing docs in README of repo
• (optional) Create COC in repo in /docs folder.
• (optional) Create Contributing in repo in /docs folder.
• (or optional) Create a single ORG repo that has those documents and link to them from the above links.

Italian translation

Hi, I would like to contribute with an italian translation. Please let me know how to do that. Thanks

[i18n] Traditional Chinese 'zho-tw' translation

Call for Translator Help

Minimal requirements

• Create a new file named zho-tw.js in the src/models/localization/ folder
• use the template below to get started, but translate some other cat facts from the other file into that file
• make a PR and mention this Issue in the description.

Starting Template Example

const facts = [
  "a single fact per a line :D",
  "..."
];

const langName = "Chinese",
  langISO = "zho",
  langLocale = "tw",
  langLocaleName = "Taiwan";

module.exports = {
  langName,
  langISO,
  langLocale,
  langLocaleName,
  code: `${langISO}-${langLocale}`,
  codeName: `${langName} (${langLocaleName})`,
  facts: facts,
};

Feel free to change the facts to be more meaningful to the location you want, as the original English facts are with America in mind, I would love to see what other places have for accurate and high-quality facts about cats.

English name of Language: Chinese
ISO 639-2/T Language Code: chi
ISO 639-2/B Language Code: zho
Language Dialect Local: Taiwan

Please make any PR that adds additional translated facts to the file.

Note: Please forgive me if I use language or terminology incorrectly, please do correct me and we will all learn together how things are expressed differently in other places.

Main Issue: #175

Migrate Server-side-tools to sst

Migrate Server-side-tools to sst

[Docs] [chore] Create documentation on programmableweb alturnative

Description

Programableweb no longer exists as of Feb 2023, We previously had a lot of exposure from their listing as a learning resource, and would like to document the free api on other platforms. rapidapi is a robust platform which has a lot of good free resources for small teams, it also gets people started using the api with code snippets and allows for people to query the api in a postman like web panel.

Tasks

• Create white rabbit organization on rapidapi
• Create Meow facts documentation as apart of the org
• update README.md with new link to the rapidapi page
• update org's documentation page to have a link to it as well

organization account
https://rapidapi.com/orghomepage/wh-iterabb-it

This API is listed publicly now here:
https://rapidapi.com/wh-iterabb-it-wh-iterabb-it-default/api/meowfacts/

We link to it, and will do our best to keep the documentation in sync

[chore] Specify a version in the package.json

we moved from 14 to 16, lets put that in the package.json for future apps to leverage

  "engines": {
    "node": "16.x"
  }

[I18N][GER] Translate the 99 catfacts into German

Description

Translate the 99 catfacts into german.

Acceptance Criteria

• Translate the 99 facts from the other models and translate those into German.

[DOCS] Update documentation

Documentation needs to have the new GET query params included, as well as new lang / i18n needs to be documented. this is almost technical debt as these features are already out the door :D

Needed to be done

• OAPI3.0 Defs updated docs/api.yaml
  • add lang GET param definition and rules
  • add count GET param definition and rules
  • add /:id GET route definition
• README.md updated
  • add lang GET param definition and rules
  • add count GET param definition and rules
  • add /:id GET route definition

[I18N][ESP] Translate the 99 catfacts into Spanish

Description

Translate the 99 catfacts into Spanish, we are targeting 2 locals for this :

1. esp-ES (Spanish/Spain)
2. esp-MX (Spanish/Mexico)

a second initiative is to support pt-BR (Portuguese/Brazil) later on.

Acceptance Criteria

• Translate and add the other 98 facts to
• Translate the 99 facts from the other models and translate those into Spanish.

[i18n] Translate and Add Japanese(jpn-ja) meow facts.

Thank you for creating such wonderful and fascinating open-source software.
I am interested in translating this project into Japanese. Would that be alright?

/options endpoint

Description of changes

Creating a new endpoint at /options which returns an array of language objects in its response.
Each local/language in the ./localization folder should get its own object.

lang object displaying the following attributes:

• locale_code - legacy locale codes which were ISO 2 digit
• iso_code - the 3 digit ISO 639-2/T Code
• full_code - both iso_code and locale_code separated by a dash -, example: "ces-cz"
• english_name - English name of Language
• local_name - local name of Language
• full_name - The full name consists of local_name, english_name and full_code, like Čeština/Czech (ces-cz)
• fact_count - the number of facts translated into this language

example of response:

{
  "lang": [
    {
      "locale_code": "cz",
      "iso_code": "ces",
      "full_code": "ces-cz",
      "local_name": "Čeština", 
      "english_name": "Czech",
      "full_name": "Čeština/Czech (ces-cz)",
      "fact_count": 94,
    },
    {
      "locale_code": "de",
      "iso_code": "deu",
      "full_code": "deu-de",
      "local_name": "Deutsch",
      "english_name": "German",
      "full_name": "Deutsch/German (deu-de)",
      "fact_count": 99,
    }
  ]
}

This will allow the discovery of which languages are available, and how many facts are available in each.