From 52802a4127427e597c9bc0d9f764b14d6751b0dd Mon Sep 17 00:00:00 2001 From: Sebastian Steiner Date: Sun, 20 Jan 2019 14:41:09 +0100 Subject: [PATCH] first attempt for unifiying readmes --- service-analysis/README.md | 14 +++++----- service-reporting/README.md | 8 +++--- service-twitter/README.md | 52 +++++++++++++++++++++---------------- 3 files changed, 42 insertions(+), 32 deletions(-) diff --git a/service-analysis/README.md b/service-analysis/README.md index 28c838b..1754807 100644 --- a/service-analysis/README.md +++ b/service-analysis/README.md @@ -1,9 +1,8 @@ # Sentiment Service - ## API -Provides a REST-API to get the average sentiment of a given list of texts -The service uses the the sentiment analysis service indico. +Provides a REST-API to get the average sentiment of a given list of texts. +The service uses the sentiment analysis service indico. `GET`: `/` Displays the expected input for a POST @@ -54,8 +53,8 @@ The indico api key can be set in the file `analysis.env`. The current key does w In case of an 503 error, you can use the `/offline_analysis`. ## run with docker -- `docker build -t sentiment_analysis .` -- `docker container run --env-file=analysis.env -d -p YOUR_PORT:8081 sentiment_analysis` +- `docker build -t service-analysis .` +- `docker container run --env-file=analysis.env -d -p YOUR_PORT:8081 service-analysis` ## run local ### requirements @@ -66,8 +65,11 @@ In case of an 503 error, you can use the `/offline_analysis`. - pip: textblob ### commands - `python3.7 sentiment_analysis.py` to start the service + +## examples - positive online sentiment test example: `curl -v -H 'content-type: application/json' -X POST http://localhost:8081 -d '[{"text":"happy birthday, i love you"}]'` - negative online sentiment test example: `curl -v -H 'content-type: application/json' -X POST http://localhost:8081 -d '[{"text":"i hate you, please die"}]'` - positive offline sentiment test example: `curl -v -H 'content-type: application/json' -X POST http://localhost:8081/offline_analysis -d '[{"text":"happy birthday, i love you"}]'` - negative offline sentiment test example: `curl -v -H 'content-type: application/json' -X POST http://localhost:8081/offline_analysis -d '[{"text":"i hate you, please die"}]'` -- health check test example: `curl -v -X GET http://localhost:8081/health` +- health check example: `curl -v -X GET http://localhost:8081/health` +- invalid input example (error: 409): `curl -v -H 'content-type: application/json' -X POST http://localhost:8081 -d '[]'` diff --git a/service-reporting/README.md b/service-reporting/README.md index cc0a95a..ae7df7b 100644 --- a/service-reporting/README.md +++ b/service-reporting/README.md @@ -28,11 +28,13 @@ Provides a REST-API to generate PDF reports for terms and their sentiment analys ``` - return: pdf file +## API errors +`TODO` + ### Term model Term(string `Name`, double `Sentiment`) ## run with docker - - `docker build -t service-reporting .` - `docker run -p YOUR_PORT:8083 service-reporting:latest` @@ -43,8 +45,8 @@ Term(string `Name`, double `Sentiment`) ### commands - `dotnet run` -## Tests +## examples - successfull pdf as application/json: `curl -X POST http://localhost:8083/generatePDF -H 'Content-Type: application/json' -d '[ { "name": "A bad term", "sentiment": 0.1 }, { "name": "Another bad term", "sentiment": 0.3 }, { "name": "A neutral term", "sentiment": 0.5 }, { "name": "A good term", "sentiment": 0.65 }, { "name": "Another good term", "sentiment": 0.9 } ] ' -vs > test1.pdf` - successfull pdf as application/base64: `curl -X POST http://localhost:8083/generatePDF -H 'Accept: application/base64' -H 'Content-Type: application/json' -d '[ { "name": "A bad term", "sentiment": 0.1 }, { "name": "Another bad term", "sentiment": 0.3 }, { "name": "A neutral term", "sentiment": 0.5 }, { "name": "A good term", "sentiment": 0.65 }, { "name": "Another good term", "sentiment": 0.9 } ] ' -vs | base64 -d > test2.pdf` - invalid sentiment value: `curl -X POST http://localhost:8083/generatePDF -H 'Content-Type: application/json' -d '[ { "name": "Term with invalid sentiment value", "sentiment": 12 } ] ' -vs && echo` -- invalid json structure: `curl -X POST http://localhost:8083/generatePDF -H 'Content-Type: application/json' -d '[ { "name1": "A term with invalid json format", "sentiment": 0.5 } ] ' -vs && echo` \ No newline at end of file +- invalid json structure: `curl -X POST http://localhost:8083/generatePDF -H 'Content-Type: application/json' -d '[ { "name1": "A term with invalid json format", "sentiment": 0.5 } ] ' -vs && echo` diff --git a/service-twitter/README.md b/service-twitter/README.md index 79630d0..839d927 100644 --- a/service-twitter/README.md +++ b/service-twitter/README.md @@ -1,38 +1,44 @@ # Twitter Service - - ## API +Provides a REST-API that mainly mirrors the search API from Twitter. +The service uses the official Twitter API. You can use the search under [http://localhost:8084/search/tweets.json?q=Google](http://localhost:8080/search/tweets.json?q=Google) where `q` is your search string. -It mainly mirrors the search API from Twitter. My implementation contains some basic fields with the same names as in -the official API. If you need more, please let me know. - - -### Example - -`curl -vs http://localhost:8084/search/tweets.json?q=Google ` - -Pipe it into e.g. `jq` for a more readable output. +`GET`: `/search/tweets.json?q=` returns tweets matching the given search term as a set of JSON objects +- param: `q` search term +example: `/search/tweets.json?q=example` +`GET`: `/actuator/health` Returns HTTP Status 200 if service is running +## API errors +`TODO` -## API Keys - -Unfortunately you have to provide your own API Keys, as sharing them is forbidden. In the worst case there would be five -people using the same keys at the same time. This probably asks for a ban. - -I really don't want to risk it, as my application for a [Twitter Developer Platform](https://developer.twitter.com/) -account was ridiculously complicated. You have to answer four questions, with at least 400 (?) words, and as detailed as -possible. My application apparently wasn't detailed enough, so they asked me follow up questions. After two emails, one -with ~1.200 words, they were finally satisfied. - +## external services +This twitter service uses the online twitter api. +Unfortunately you have to provide your own API Keys, as sharing them is forbidden. In the worst case there would be five people using the same keys at the same time. This probably asks for a ban. +I really don't want to risk it, as my application for a [Twitter Developer Platform](https://developer.twitter.com/) account was ridiculously complicated. You have to answer four questions, with at least 400 (?) words, and as detailed as possible. My application apparently wasn't detailed enough, so they asked me follow up questions. After two emails, one with ~1.200 words, they were finally satisfied. Furthermore people with an existing account, like I had, can't create new apps anymore, unless they apply again. +So I would advise you to [apply for an account](https://developer.twitter.com/en/apply-for-access) yourself, or maybe ask someone else from the group if they have a spare key. -So I would advise you to [apply for an account](https://developer.twitter.com/en/apply-for-access) yourself, or maybe -ask someone else from the group if they have a spare key. +The twitter api keys can be set in the file `TODO`. The keys then go into `application.yml` below `oauth:`, i.e. `consumer-key`, `consumer-secret`, `access-token`, `access-token-secret`. + +## run with docker +- `docker build -t service-twitter .` +- `docker container run --env-file=` TODO `-d -p YOUR_PORT:8084 service-twitter` + +## run local +### requirements +`TODO` +### commands +`TODO` + +## examples +- API call example: `curl -vs http://localhost:8084/search/tweets.json?q=Google` + - Pipe it into e.g. `jq` for a more readable output. +- health check test example: `curl -v -X GET http://localhost:8084/actuator/health` -- 2.43.0