diff --git a/README.md b/README.md index 097b9c3c..235dee83 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,35 @@ # relax-api A REST API to integrate RelaX with third-party applications. -This implementation provides a workaround to facilitate the integration of [RelaX - relational algebra calculator](https://dbis-uibk.github.io/relax/) with third-party applications/systems. **Why is it necessary? Because RelaX Query API does not work as an actual REST API!** RelaX is implemented in React JS, a UI framework, to load data asynchronously on a single page application. This approach returns a Web page that does not include the data. More information regarding this issue can be found [here](https://github.com/dbis-uibk/relax/pull/148). - -## HOW TO BUILD AND RUN IT: - -* Install Git (https://github.com/git-guides/install-git). -* Install Yarn (https://yarnpkg.com/). -* Install Node@12 (https://nodejs.org/en/). -* Clone this repo and set it as your working directory. - -```bash -git clone https://github.com/rlaiola/relax-api.git -cd relax-api -``` - -* Clone RelaX repo* and checkout the static files (branch `gh-pages`). - -```bash -mkdir dist && \ -cd dist && \ -git clone https://github.com/rlaiola/relax.git && \ -cd relax && \ -git branch -a && \ -git checkout origin/gh-pages && \ -git checkout gh-pages && \ -git branch && \ -cd ../.. -``` - +This implementation provides a workaround to facilitate the integration of [RelaX - relational algebra calculator](https://dbis-uibk.github.io/relax/) with third-party applications/systems. **Why is it necessary? Because RelaX Query API does not work as an actual REST API!** RelaX is implemented in React JS, a UI framework, to load data asynchronously on a single page application. +This approach returns a Web page that does not include the data. More information regarding this issue can be found [here](https://github.com/dbis-uibk/relax/pull/148). + +## How To Build And Run It + +* Install [Git](https://github.com/git-guides/install-git); +* Install [Yarn](https://yarnpkg.com/); +* Install [Node](https://nodejs.org/en/); +* Clone this repo and set it as your working directory; + + ```sh + git clone --branch api https://github.com/rlaiola/relax.git + cd relax + ``` + +* Clone RelaX repo* and checkout the static files (branch `gh-pages`); + + ```sh + mkdir dist && \ + cd dist && \ + git clone https://github.com/rlaiola/relax.git && \ + cd relax && \ + git branch -a && \ + git checkout origin/gh-pages && \ + git checkout gh-pages && \ + git branch && \ + cd ../.. + ``` + **NOTE:** As of Jul 17th 2021, RelaX main repo had not yet accepted the changes necessary for this REST API to work. That's the reason why you should clone the forked project. * Execute `yarn install` to install all dependencies. @@ -36,51 +37,67 @@ cd ../.. **NOTE:** This implementation uses ports 8080 (RelaX Web app) and 3000 (RelaX Query API). These ports can me changed by setting the variables RELAX_PORT and RELAX_API_PORT, respectively, as shown below: -```bash -RELAX_PORT=80 RELAX_API_PORT=4000 yarn serve -``` + ```sh + RELAX_PORT=80 RELAX_API_PORT=4000 yarn serve + ``` -## HOW TO TEST IT: +## How To Test It * Make sure you followed the steps above to [build and run](#how-to-build-and-run-it) the application; -* Open a Web browser window and visit the URL http://localhost:8080. In case you started the application to listen in a different port number (`RELAX_PORT` variable), change the URL accordingly. Voilà! RelaX Web application should work properly. +* Open a Web browser window and visit the URL [http://localhost:8080](http://localhost:8080). In case you started the application to listen in a different port number (`RELAX_PORT` variable), change the URL accordingly. Voilà! RelaX Web application should work properly. -

- -

+

+ +

* Run the following command to test RelaX Query API. In case you started the application to listen in a different port number (`RELAX_API_PORT` variable), change the URL accordingly. You should get the query result encoded in JSON format. -```bash -curl http://127.0.0.1:3000/relax/api/local/uibk/local/0?query=UiBqb2luIFMgam9pbiBU -``` + ```sh + curl http://127.0.0.1:3000/relax/api/local/uibk/local/0?query=UiBqb2luIFMgam9pbiBU + ```

-## Increasing GitHub rate limit for API requests using Basic Authentication +## How To Increasing Github Rate Limit For API Requests Using Basic Authentication -RelaX Web application and API may need to make calls to GitHub API (i.e., to download datasets specified in GitHub Gists). According to the [documentation](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting), _"for unauthenticated requests, the rate limit allows for up to 60 requests per hour. Unauthenticated requests are associated with the originating IP address, and not the user making requests."_ On the other hand, _"for API requests using Basic Authentication ..., you can make up to 5,000 requests per hour."_ Follow the steps below in order to take advantage of a larger request limit: +RelaX Web application and API may need to make calls to GitHub API (i.e., to download datasets specified in GitHub Gists). +According to the [documentation](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting), _"for unauthenticated requests, the rate limit allows for up to 60 requests per hour. Unauthenticated requests are associated with the originating IP address, and not the user making requests."_ +On the other hand, _"for API requests using Basic Authentication ..., you can make up to 5,000 requests per hour."_ Follow the steps below in order to take advantage of a larger request limit: 1. Read these [instructions](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/about-authentication-to-github#authenticating-with-the-api) to create a personal access token to authenticate with GitHub API. 1. Then, start the application setting the GITHUB_ACCESS_TOKEN environment variable (replace the word 'my_token' with the actual personal access token generated in the previous step). -```bash -GITHUB_ACCESS_TOKEN=my_token yarn serve -``` - + ```sh + GITHUB_ACCESS_TOKEN=my_token yarn serve + ``` + **NOTE:** You can check the current and remaining limits using the following command (replace the word 'my_token' with the actual personal access token created before). For details check the [documentation](https://docs.github.com/en/rest/guides/getting-started-with-the-rest-api). -```bash -curl -H "Authorization: token my_token" -I https://api.github.com/users/octocat/orgs -``` + ```sh + curl -H "Authorization: token my_token" -I https://api.github.com/users/octocat/orgs + ``` + +## How to Contribute + +If you would like to help contribute to this project, please see [CONTRIBUTING](https://github.com/rlaiola/relax/blob/api/CONTRIBUTING.md). + +Before submitting a PR consider building and testing a Docker image locally and checking your code with Super-Linter: + + ```sh + docker run --rm \ + -e RUN_LOCAL=true \ + -e USE_FIND_ALGORITHM=true \ + --env-file ".github/super-linter.env" \ + -v "$PWD":/tmp/lint ghcr.io/github/super-linter:slim-v5 + ``` -## LICENSE: +## License -Copyright 2021 Rodrigo Laiola Guimarães +Copyright Universidade Federal do Espirito Santo (Ufes) This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -97,6 +114,6 @@ along with this program. If not, see . This program is released under license GNU GPL v3+ license. -## SUPPORT: +## Support -Please report any issues with relax-api at https://github.com/rlaiola/relax-api/issues +Please report any issues with _relax_ at [https://github.com/rlaiola/relax/issues](https://github.com/rlaiola/relax/issues)