Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@rlaiola
rlaiola committed Sep 28, 2023
1 parent 52e9ada commit 0d010fa
Showing 1 changed file with 69 additions and 52 deletions.
121 changes: 69 additions & 52 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,86 +1,103 @@
# 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.
* Execute `yarn serve` to locally run the Web application on port 8080 and the Query API on port 3000.

**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.

<p align="center">
<img src="imgs/relax_web_app.png" width=800 />
</p>
<p align="center">
<img src="imgs/relax_web_app.png" width=800 />
</p>

* 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
```

<p align="center">
<img src="imgs/relax_api.png" width=800 />
</p>

## 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
Expand All @@ -97,6 +114,6 @@ along with this program. If not, see <https://www.gnu.org/licenses/>.

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)

0 comments on commit 0d010fa

Please sign in to comment.