Added proper docs in the README

FullStackBulletin · Jul 31, 2023 · b5ea9e7 · b5ea9e7
1 parent 9294c7f
commit b5ea9e7
Show file tree

Hide file tree

Showing 2 changed files with 198 additions and 2 deletions.
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 FullStack Bulletin
+Copyright (c) 2023 Luciano Mammino
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -23,6 +23,202 @@ Returns statistics about all the available quotes.
 curl https://fullStackbulletin.github.io/tech-quotes/quotes/stats.json | jq .
 ```
 
+Returns
 
+```json
+{
+  "total": 53,
+  "all": "https://fullStackbulletin.github.io/tech-quotes/quotes/all.json",
+  "first": "https://fullStackbulletin.github.io/tech-quotes/quotes/0.json",
+  "last": "https://fullStackbulletin.github.io/tech-quotes/quotes/52.json",
+  "urlPrefix": "https://fullStackbulletin.github.io/tech-quotes/quotes"
+}
+```
+
+### `/quotes/all.json`
+
+Returns all the quotes
+
+#### Example
+
+```bash
+curl https://fullStackbulletin.github.io/tech-quotes/quotes/all.json | jq .
+```
+
+Returns
+
+```json
+{
+  "metadata": {
+    "total": 53,
+    "first": 0,
+    "last": 52
+  },
+  "quotes": [
+    {
+      "id": 0,
+      "text": "Technology is anything that wasn't around when you were born",
+      "author": {
+        "id": "alan-kay",
+        "name": "Alan Kay",
+        "description": "Computer Scientist",
+        "wiki": "https://en.wikipedia.org/wiki/Alan_Kay",
+        "url": "https://fullStackbulletin.github.io/tech-quotes/authors/alan-kay.json"
+      },
+      "url": "https://fullStackbulletin.github.io/tech-quotes/quotes/0.json"
+    },
+    {
+      "id": 1,
+      "text": "Any sufficiently advanced technology is equivalent to magic",
+      "author": {
+        "id": "arthur-c-clarke",
+        "name": "Arthur C. Clarke",
+        "description": "Author",
+        "wiki": "https://en.wikipedia.org/wiki/Arthur_C._Clarke",
+        "url": "https://fullStackbulletin.github.io/tech-quotes/authors/arthur-c-clarke.json"
+      },
+      "url": "https://fullStackbulletin.github.io/tech-quotes/quotes/1.json"
+    },
+    {
+      "//": "...",
+    }
+  ]
+}
+```
+
+### `/quotes/{quoteId}.json`
+
+Gets a single quote by ID:
+
+#### Example
+
+```bash
+curl https://fullStackbulletin.github.io/tech-quotes/quotes/17.json | jq .
+```
+
+Returns
+
+```json
+{
+  "id": 17,
+  "text": "The art challenges the technology, and the technology inspires the art",
+  "author": {
+    "id": "john-lasseter",
+    "name": "John Lasseter",
+    "description": "Director",
+    "wiki": "https://en.wikipedia.org/wiki/John_Lasseter",
+    "url": "https://fullStackbulletin.github.io/tech-quotes/authors/john-lasseter.json"
+  },
+  "url": "https://fullStackbulletin.github.io/tech-quotes/quotes/17.json"
+}
+```
+
+
+### `/authors/stats.json`
+
+Gets statistics abouts the authors
+
+#### Example
+
+```bash
+curl https://fullStackbulletin.github.io/tech-quotes/authors/stats.json | jq .
+```
+
+Returns
+
+```json
+{
+  "total": 51,
+  "all": "https://fullStackbulletin.github.io/tech-quotes/authors/all.json",
+  "urlPrefix": "https://fullStackbulletin.github.io/tech-quotes/authors"
+}
+```
+
+### `/authors/all.json`
+
+Gets the list of all available authors
+
+#### Example
+
+```bash
+curl https://fullStackbulletin.github.io/tech-quotes/authors/all.json | jq .
+```
+
+Returns
+
+```json
+{
+  "metadata": {
+    "total": 51
+  },
+  "authors": [
+    "alan-kay",
+    "arthur-c-clarke",
+    "mark-kennedy",
+    "thomas-edison",
+    "albert-einstein",
+    "elbert-hubbard",
+    "douglas-adams",
+    "...",
+    "john-brunner"
+  ]
+}
+```
+
+### `/authors/{authorId}.json`
+
+Gets the details and the quote of a given author
+
+#### Example
+
+```bash
+curl https://fullStackbulletin.github.io/tech-quotes/authors/andrew-s-tanenbaum.json | jq .
+```
+
+Returns
+
+```json
+{
+  "id": "andrew-s-tanenbaum",
+  "name": "Andrew S. Tanenbaum",
+  "description": "Computer Scientist",
+  "wiki": "https://en.wikipedia.org/wiki/Andrew_S._Tanenbaum",
+  "url": "https://fullStackbulletin.github.io/tech-quotes/authors/andrew-s-tanenbaum.json",
+  "quotes": [
+    {
+      "id": 31,
+      "text": "Never underestimate the bandwidth of a station wagon full of tapes hurtling down the highway",
+      "author": {
+        "id": "andrew-s-tanenbaum",
+        "name": "Andrew S. Tanenbaum",
+        "description": "Computer Scientist",
+        "wiki": "https://en.wikipedia.org/wiki/Andrew_S._Tanenbaum",
+        "url": "https://fullStackbulletin.github.io/tech-quotes/authors/andrew-s-tanenbaum.json"
+      },
+      "url": "https://fullStackbulletin.github.io/tech-quotes/quotes/31.json"
+    }
+  ]
+}
+```
+
+## Suggest a quote
+
+If you want to suggest a new tech quote here's how you can do that.
+
+- [Fork this repository](https://github.com/FullStackBulletin/tech-quotes/fork)
+- Edit the file [`src/quotes.ts`](/src/quotes.ts) and append the new fact at the bottom (make sure to follow the spec provided by the specific TypeScript types).
+- Run `npm run test && npm run build`
+- If all looks good, commit your changes
+- Open a PR against the original repository
+
+
+## Contributing
+
+Everyone is very welcome to contribute to this project.
+You can contribute just by submitting bugs or suggesting improvements by
+[opening an issue on GitHub](https://github.com/FullStackBulletin/tech-quotes/issues).
+
+
+## License
 
-WIP
+Licensed under [MIT License](LICENSE). © Luciano Mammino.