5 |
6 | ## Our Pledge:
7 |
8 | In the interest of fostering an open and welcoming environment, we as
9 | contributors and maintainers pledge to making participation in our project and
10 | our community a harassment-free experience for everyone, regardless of age, body
11 | size, disability, ethnicity, sex characteristics, gender identity and expression,
12 | level of experience, education, socio-economic status, nationality, personal
13 | appearance, race, religion, or sexual identity and orientation.
14 |
15 |
16 |
17 | ## Our Standards:
18 |
19 | Examples of behavior that contributes to creating a positive environment
20 | include:
21 |
22 | * Using welcoming and inclusive language
23 | * Being respectful of differing viewpoints and experiences
24 | * Gracefully accepting constructive criticism
25 | * Focusing on what is best for the community
26 | * Showing empathy towards other community members
27 |
28 | Examples of unacceptable behavior by participants include:
29 |
30 | * The use of overly sexualized language or imagery and unwelcome sexual attention or
31 | advances
32 | * Trolling, insulting/derogatory comments, and personal or political attacks
33 | * Public or private harassment
34 | * Publishing others' private information, such as a physical or electronic
35 | address, without explicit permission
36 | * Other conduct which could reasonably be considered inappropriate in a
37 | businessy-casual setting
38 |
39 |
40 |
41 | ## Our Responsibilities:
42 |
43 | Project maintainers are responsible for clarifying the standards of acceptable
44 | behavior and are expected to take appropriate and fair corrective action in
45 | response to any instances of unacceptable behavior.
46 |
47 | Project maintainers have the right and responsibility to remove, edit, or
48 | reject comments, commits, code, wiki edits, issues, and other contributions
49 | that are not aligned to this Code of Conduct, or to ban temporarily or
50 | permanently any contributor for other behaviors that they deem inappropriate,
51 | threatening, offensive, or harmful.
52 |
53 |
54 |
55 | ## Scope:
56 |
57 | This Code of Conduct applies both within project spaces and in public spaces
58 | when an individual is representing the project or its community. Examples of
59 | representing a project or community include using an official project e-mail
60 | address, posting via an official social media account, or acting as an appointed
61 | representative at an online or offline event. Representation of a project may be
62 | further defined and clarified by project maintainers.
63 |
64 |
65 |
66 | ## Enforcement:
67 |
68 | Instances of abusive, harassing, or otherwise unacceptable behavior may be
69 | reported by contacting the project team at contact@sv443.net. All
70 | complaints will be reviewed and investigated and will result in a response that
71 | is deemed necessary and appropriate to the circumstances. The project team is
72 | obligated to maintain confidentiality with regard to the reporter of an incident.
73 | Further details of specific enforcement policies may be posted separately.
74 |
75 | Project maintainers who do not follow or enforce the Code of Conduct in good
76 | faith may face temporary or permanent repercussions as determined by other
77 | members of the project's leadership.
78 |
79 |
80 |
81 | ## Attribution:
82 |
83 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
84 | available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
85 |
86 | [homepage]: https://www.contributor-covenant.org
87 |
88 | For answers to common questions about this code of conduct, see
89 | https://www.contributor-covenant.org/faq
90 |
--------------------------------------------------------------------------------
/.github/Contributing.md:
--------------------------------------------------------------------------------
1 |
2 |
3 | # The code in this repo moved
4 | The latest source code of JokeAPI lives on my own Git server for now: https://git.sv443.net/sv443/JokeAPI-v2
5 |
6 | If you have any issues, please still use this repository on GitHub to submit them.
7 | For pull requests however, please use the new repo.
8 |
9 |
10 |
11 |
12 |
13 | # Contributing Guide
14 | This guide will tell you how you can and should contribute to JokeAPI.
15 | Not following it might cause me to reject your changes but at the very least we will both lose time.
16 | So please read this guide before contributing. Thanks :)
17 |
18 | ## Table of Contents:
19 | - [Submitting or editing jokes](#submitting-or-editing-jokes)
20 | - [Contributing to JokeAPI's code](#submitting-code)
21 | - [Submitting a translation](#submitting-translations)
22 | - [Tips and Tricks for contributing](#other-nice-to-know-stuff)
23 |
24 |
25 |
26 | ## Submitting or editing jokes:
27 | If you want to submit or edit jokes, you can find them in the `jokes-xy.json` files in [`data/jokes/`](../data/jokes/)
28 | To submit your changes, create a pull request. Also make sure to follow the [code contribution instructions.](#submitting-code)
29 |
30 | If you want a joke to be edited, re-flagged or deleted, please [submit a new issue here.](https://github.com/Sv443/JokeAPI/issues/new?assignees=Sv443&labels=joke+edit&template=3_edit_a_joke.md)
31 | Keep in mind that deleting jokes will be my last resort. I will also not remove jokes based on certain world views and opinions to uphold the API's main purpose; to provide jokes for everyone's taste.
32 |
33 |
34 |
35 |
36 | ## Submitting code:
37 | 1. [Read the Code_of_Conduct.md file](./Code_of_Conduct.md) (TLDR: just behave in a friendly manner).
38 | 2. Fork the repository. Afterwards, clone or download it and locate the folder where it is contained.
39 | 3. Make the changes you want to make to the code.
40 | 4. Run the script `npm run all` which will run these commands:
41 | - `npm run validate-jokes` to make sure all jokes are formatted correctly.
42 | - `npm run validate-ids` to verify that all jokes have the correct ID.
43 | - `npm run lint` to check the code for any warnings or errors.
44 | - `npm run dep-graph` to generate a new dependency graph.
45 | - `npm run generate-changelog` to generate a Markdown changelog out of the plaintext one.
46 | - `npm run test`, which runs the unit tests for JokeAPI. If you are colorblind, you can run the command `npm run test-colorblind` (will turn green into cyan and red into magenta).
47 | 5. Run JokeAPI locally by running the command `node JokeAPI`, request some jokes and test the areas you modified / added to make sure everything still works.
48 | 6. Add yourself to the `contributors` object in the [`package.json`](https://git.sv443.net/sv443/JokeAPI-v2/src/main/package.json) file :)
49 |
50 | 7. Submit a pull request on your forked repository, selecting `Sv443/JokeAPI` as the base repo and `master` as the base branch and selecting `YourUsername/JokeAPI` as the head repo and `YourBranch` as the compare branch
51 | - If your pull request is not ready to be merged yet, you can add `[WIP]` to the beginning of the title which will tell the repo maintainer(s) and automated scripts not to merge it yet.
52 | 8. Request a review from me (Sv443).
53 | 9. Check if the CI script and other checks for your pull request were successful (they can be found below the comments).
54 | - **If they were unsuccessful:** view the log, fix the errors, commit the code and push to the same branch. This will automatically update your pull request and re-run the checks.
55 | 10. Once the pull request is approved and merged, you can delete the source branch and your forked repo if you want to.
56 | - **If it isn't**, please read the comments from the reviewer(s) and make the necessary changes.
57 |
58 |
59 |
60 | ## Submitting Translations:
61 | If you want to submit a translation, please follow these steps:
62 | 1. Find your language's two-character code in the file [`data/languages.json`](https://git.sv443.net/sv443/JokeAPI-v2/src/main/data/languages.json). You'll need to specify it for every translation.
63 | 2. Translate coded error messages in the file [`data/errorMessages.js`](https://git.sv443.net/sv443/JokeAPI-v2/src/main/data/errorMessages.js) by following the style of the other translations.
64 | 3. Translate the generic strings inside of the file [`data/translations.json`](https://git.sv443.net/sv443/JokeAPI-v2/src/main/data/translations.json) by also following the style of the other translations.
65 | 4. Add yourself to the `contributors` object in the [`package.json`](https://git.sv443.net/sv443/JokeAPI-v2/src/main/package.json) file :)
66 |
67 |
68 |
69 | ## Other nice-to-know stuff:
70 | - I really recommend using [Visual Studio Code](https://code.visualstudio.com/) with the extension [`fabiospampinato.vscode-highlight`](https://marketplace.visualstudio.com/items?itemName=fabiospampinato.vscode-highlight) - it will add custom styling to the syntax highlighting in the editor and make the code easier to read and work with.
71 | - If you want to generate a dependency graph, you need to install [Graphviz](https://graphviz.gitlab.io/download/) and add the path to the `bin` folder to your `%PATH%` / `$PATH` environment vaiable. Then, run the command `npm run dependency-graph` and open the file [`dev/dependency-graph.html`](../dev/dependency-graph.html) in a browser.
72 | - If you need to add an authorization token, you can generate one or multiple tokens with the command `npm run add-token [amount]`. If you omit the "amount" parameter, the script will generate a single token. After you run the command, the tokens will be listed in the console and you can now (after restarting JokeAPI) use it in the `Authorization` header to gain unlimited access to JokeAPI [(better explanation here).](https://jokeapi.dev/#api-tokens)
73 |
74 |
75 |
76 | ## If you need any help, feel free to contact me through [Discord](https://sv443.net/discord) (fastest way to contact me) or [E-Mail](mailto:contact@sv443.net?subject=Questions%20about%20contributing%20to%20JokeAPI)
77 |
--------------------------------------------------------------------------------
/.github/FUNDING.yml:
--------------------------------------------------------------------------------
1 | github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
2 | patreon: Sv443
3 | open_collective: #
4 | ko_fi: Sv443_
5 | tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
6 | community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
7 | liberapay: # Replace with a single Liberapay username
8 | issuehunt: # Replace with a single IssueHunt username
9 | otechie: # Replace with a single Otechie username
10 | custom: ['paypal.me/SvenFehler']
11 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/1_bug_report.md:
--------------------------------------------------------------------------------
1 | ---
2 | name: Bug report
3 | about: Create a bug report to help improve JokeAPI
4 | title: ''
5 | labels: bug
6 | assignees: Sv443
7 |
8 | ---
9 |
10 | ## Describe the bug
11 | A clear and concise description of what the bug is.
12 |
13 | ## Steps to reproduce
14 | Steps to reproduce the unwanted behavior:
15 | 1. Go to '...'
16 | 2. Click on '....'
17 | 3. Scroll down to '....'
18 | 4. See error
19 |
20 | ## Expected behavior
21 | A clear and concise description of what you expected to happen.
22 |
23 | ## Screenshots
24 | If applicable and possible, add screenshots to help explain your problem.
25 |
26 | ## Additional information
27 | - OS: [e.g. Windows 10 - Build 1803]
28 | - Your client's language [e.g. Node.js, Java, ...]
29 | - Your client's language's version [e.g. Node.js v12.0.0]
30 | - The endpoint(s) you are having problems with (if applicable)
31 |
32 | ## Code snippet
33 | If this bug is caused by a piece of code, send the code right here and mark the line where it is caused.
34 | I only know JavaScript, C++ and C#, but I can probably interpret other languages.
35 |
36 | ## Additional context
37 | Add any other context about the problem here.
38 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/2_feature_request.md:
--------------------------------------------------------------------------------
1 | ---
2 | name: Feature request
3 | about: Suggest an idea / feature for JokeAPI
4 | title: ''
5 | labels: enhancement
6 | assignees: Sv443
7 |
8 | ---
9 |
10 | ## Is your feature request related to a problem? Please describe.
11 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
12 | If it is related to a GitHub issue or merge request, provide the issue's or merge request's number here [e.g. This feature request is related to issue #3]
13 |
14 | ## Describe the solution you'd like
15 | A clear and concise description of what you want to happen.
16 |
17 | ## Describe alternatives you've considered
18 | A clear and concise description of any alternative solutions or features you've considered and how they are inferior to your proposed feature.
19 |
20 | ## Additional context
21 | Add any other context or screenshots about the feature request here.
22 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/3_edit_a_joke.md:
--------------------------------------------------------------------------------
1 | ---
2 | name: Edit a joke
3 | about: Suggest a joke that needs to be edited or removed
4 | title: ''
5 | labels: joke edit
6 | assignees: Sv443
7 |
8 | ---
9 |
10 | ## The joke's ID:
11 |
12 |
13 |
14 | ## Why the joke should be edited or removed:
15 |
16 |
17 | ## Alternative to the joke:
18 |
19 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/4_add_dependent.md:
--------------------------------------------------------------------------------
1 | ---
2 | name: Dependent
3 | about: Request your project to be added to the dependent lists in the readme and documentation or suggest an edit to a dependent
4 | title: 'New dependent: '
5 | labels: dependent
6 | assignees: Sv443
7 |
8 | ---
9 |
10 |
15 |
16 | ## Link to the project:
17 |
18 | ```
19 | https://github.com/example/My_Project
20 | ```
21 |
22 |
23 |
24 |
25 | ## Link to my personal website / GitHub page (optional):
26 |
27 | ```
28 | https://github.com/example
29 | ```
30 |
31 |
32 |
33 |
34 | ## Is your project explicit or unsafe for minors to view?
35 |
36 | - [ ] **Yes**, it contains explicit material
37 | - [ ] **No**, it doesn't contain explicit material
38 |
39 |
40 |
41 |
42 | ## Notes:
43 |
44 |
45 |
46 |
47 |
48 |
49 | ## Checklist:
50 | - [ ] I have added my project's name to the title of this issue
51 | - [ ] I have filled out at least the first URL (second one is optional)
52 | - [ ] I have specified whether or not my project is explicit
53 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/5_wrong_translation.md:
--------------------------------------------------------------------------------
1 | ---
2 | name: Wrong Translation(s)
3 | about: Use this template if you noticed one or multiple wrong translations
4 | title: ''
5 | labels: translation
6 | assignees: Sv443
7 |
8 | ---
9 |
10 | ## Language code of the translation(s):
11 |
12 | **`xy`**
13 |
14 |
15 |
16 |
17 | ## Full translation text (or translation key):
18 |
19 |
20 | ```
21 | A horse walks into a bar...
22 | ```
23 |
24 |
25 |
26 |
27 | ## The correct version of this translation / these translations:
28 |
29 | ```
30 | A horse runs into a bar...
31 | ```
32 |
33 |
34 |
35 |
36 | ## Checklist:
37 | - [ ] I have verified that the fixed translation I provided is (to my knowledge) correct
38 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/config.yml:
--------------------------------------------------------------------------------
1 | ---
2 | blank_issues_enabled: true
3 | contact_links:
4 | -
5 | name: "Documentation"
6 | about: "Please read the documentation before opening a new issue"
7 | url: "https://jokeapi.dev/"
8 | -
9 | name: "Discussions"
10 | about: "If there's some topic you want to talk about, please open a new thread on the JokeAPI discussion board"
11 | url: "https://github.com/Sv443/JokeAPI/discussions"
12 | -
13 | name: "Chat"
14 | about: "If you want to chat with the JokeAPI community, you can join my Discord server"
15 | url: "https://sv443.net/discord"
16 |
--------------------------------------------------------------------------------
/.github/SECURITY.md:
--------------------------------------------------------------------------------
1 | # Security Policy
2 |
3 | ## Reporting a Vulnerability
4 | To report a vulnerability or security issue, please directly contact me via [Email](mailto:contact@sv443.net) or [Discord](https://sv443.net/discord).
5 | Please **do not** create a GitHub issue!
6 |
7 | ## Supported Versions
8 | These versions are still supported and will be receiving security updates:
9 | | Version | Supported | Location | Status |
10 | | --- | --- | --- | --- |
11 | | v1.0 | ❌ | `/` | deprecated |
12 | | v1.1 | ❌ | `/` | deprecated |
13 | | v2.0 | ❌ | `v2` | outdated / unavailable |
14 | | v2.1 | ❌ | `v2` | outdated / unavailable |
15 | | v2.2 | ❌ | `v2` | outdated / unavailable |
16 | | v2.3 | ✅ | `v2` | active |
17 |
18 | Location = subdomain or part of the URL path (eg. `/jokeapi/v2/` or `v2.jokeapi.dev`)
19 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 |
2 |
3 | # The code in this repo moved
4 | The latest source code of JokeAPI lives on my own Git server for now: https://git.sv443.net/sv443/JokeAPI-v2
5 |
6 | If you have any issues, please still use this repository on GitHub to submit them.
7 | For pull requests however, please use the new repo.
8 |
9 |
21 |
22 | A free and open REST API that delivers consistently formatted jokes in JSON, XML, YAML, or plain text.
23 | Powerful filters allow you to get just the jokes you want - no sign-up needed. Comes with CORS support.
24 |
25 |
26 |
27 | [](https://status.sv443.net/) [](https://snyk.io/test/github/Sv443-Network/JokeAPI) [](https://sv443.net/LICENSE)
28 | [](https://dc.sv443.net/) [](https://github.com/Sv443-Network/JokeAPI/issues) [](https://github.com/Sv443-Network/JokeAPI/stargazers)
29 |
30 |
31 |
32 |
33 |
34 | > [!WARNING]
35 | > JokeAPI contains a very wide variety of jokes, some of which can be seen as quite offensive.
36 | > They can be reliably filtered out using the parameters [`?blacklistFlags`](https://jokeapi.dev/#flags-param) and [`?safe-mode`](https://jokeapi.dev/#safe-mode).
37 | > Still, use this API at your own risk!
38 |
39 | > [!NOTE]
40 | > JokeAPI is free to use, so it relies on donations to cover the costs.
41 | > If you enjoy using it, [please consider supporting the development ❤️](https://github.com/sponsors/Sv443)
42 |
43 | > [!NOTE]
44 | > If you want to contribute to JokeAPI (code, jokes or translations), please refer to the [contributing guide.](./.github/Contributing.md)
45 | > Also make sure to use the repo at https://git.sv443.net/sv443/JokeAPI-v2
46 |
47 |
48 |
49 | ## Community-made wrapper libraries:
50 | - C#
51 | - Dart
52 | - Go
53 | - Java (com.github.the-codeboy.Jokes4J)
54 | - Java (com.simtechdata.jokeapi)
55 | - Kotlin, Java & Android (net.thauvin.erik.jokeapi)
56 | - Java (uz.khurozov.jokeapi-java)
57 | - Node.js
58 | - Odin
59 | - PHP
60 | - Python
61 | - Rust
62 | - TypeScript
63 |
64 |
65 |
66 | ## Some projects that use JokeAPI:
67 |
68 | | Project | Author |
69 | | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
70 | | [dozens Advices](https://github.com/ZephyrVentum/dozens-Advices) | [ZephyrVentum](https://github.com/ZephyrVentum) |
71 | | [Shadow](https://github.com/QGIsK/Shadow) | [QGIsK](https://github.com/QGIsK) |
72 | | [Jokepy](https://github.com/aksty/Jokepy) | [aksty](https://github.com/aksty) |
73 | | [Dark1](https://github.com/whiteadi/Dark1) | [whiteadi](https://github.com/whiteadi) |
74 | | [Prejudice Networks](https://github.com/LiamTownsley/Prejudice-Networks) | [Liam Townsley](https://github.com/LiamTownsley) |
75 | | [https://irshad.ml/humour.html](https://irshad.ml/humour.html) | [draco-malfoy](https://github.com/draco-malfoy) |
76 | | [Random Joke Generator with Flutter](https://github.com/variousnabil/Random-Joke-Generator-with-Flutter) | [variousnabil](https://github.com/variousnabil) |
77 | | [comma](https://thatcopy.pw/comma) | [ThatCopy](https://github.com/ThatCopy) |
78 | | [Joke Teller](https://github.com/AlHood77/Joke_Teller) | [AlHood77](https://github.com/AlHood77) |
79 | | [Jokes plugin for Craft CMS 3.x](https://github.com/remcoov/jokes) | [remcoov](https://github.com/remcoov) |
80 | | [PoshBot.Joker](https://github.com/ToastIT-dev/PoshBot.Joker) | [ToastIT-dev](https://github.com/ToastIT-dev) |
81 | | [JokeAPI_ComputerCraft](https://github.com/Sv443-Network/JokeAPI_ComputerCraft) | [Sv443](https://github.com/Sv443) |
82 | | [Dev Dad Jokes](https://github.com/jonathanbossenger/devdadjokes) | [Jonathan Bossenger](https://github.com/jonathanbossenger) |
83 |
84 |
99 |
100 |
101 |
102 |
103 |
104 | Made with ❤️ by [Sv443](https://github.com/Sv443) and [contributors](https://github.com/Sv443-Network/JokeAPI/graphs/contributors)
105 | Like JokeAPI? Please consider [supporting the development](https://github.com/sponsors/Sv443)
106 |
107 |
2 |
3 | # The code in this repo moved
4 | The latest source code of JokeAPI lives on my own Git server for now: https://git.sv443.net/sv443/JokeAPI-v2
5 |
6 | If you have any issues, please still use this repository on GitHub to submit them.
7 | For pull requests however, please use the new repo.
8 |
9 |