Merge pull request #357 from bbilly1/bbilly1-apidocs

add API documentation with get vote example

1 files changed, 31 insertions, 0 deletions

diff --git a/README.md b/README.md
index eb81915..af4fcb9 100644
--- a/README.md
+++ b/README.md
@@ -36,6 +36,37 @@ and estimates based on view\like ratios.
 
 You can learn more at our website at: [returnyoutubedislike.com](https://www.returnyoutubedislike.com/)
 
+## API documentation
+
+Third party use of this open API is allowed with the following restrictions:
+
+- **Attribution**: This project should be clearly attributed with either a link to this repo or a link to [returnyoutubedislike.com](https://returnyoutubedislike.com/).
+- **Rate Limiting**: There are per client rate limits in place of 100 per minute and 10'000 per day. This will return a *429* status code indicating that your application should back off.
+
+The API is accessible over the following base URL:  
+https://returnyoutubedislikeapi.com  
+
+List of available endpoints is available here:  
+https://returnyoutubedislikeapi.com/swagger/index.html
+
+### Get votes
+Example to get votes of a given YouTube video ID:  
+`/votes?videoId=kxOuG8jMIgI`
+
+```json
+{
+    "id": "kxOuG8jMIgI",
+    "dateCreated": "2021-12-20T12:25:54.418014Z",
+    "likes": 27326,
+    "dislikes": 498153,
+    "rating": 1.212014408444885,
+    "viewCount": 3149885,
+    "deleted": false
+}
+```
+
+None existing YouTube ID will return status code *404* "Not Found".  
+Wrong formed YouTube ID will return *400* "Bad Request".
 
 ## HELP WANTED