Skip to content

Latest commit

 

History

History
222 lines (155 loc) · 11.1 KB

README.md

File metadata and controls

222 lines (155 loc) · 11.1 KB
Raw

Ecoindex Back For Front

This project aims to provide a simple back for front for ecoindex API project. It is mainly used by the ecoindex browser plugin.

It offers a way to retrieve easily the latest results for a given page, and also for the current website

It is built in Golang and Fiber to provide great performance and be as light as possible

🛠️ Tech Stack

🛠️ Install Dependencies

go mod download

🧑🏻‍💻 Usage

To start the project, you first need configure your .env file and provide the url of the ecoindex API you want to reach by setting the environment variable API_URL. Default is set to https://ecoindex.p.rapidapi.com.

cp .env.dist .env

If you use production API url, you have to request an API key on RapidAPI platform. Once you get your API Key, you can set the env variable API_KEY

API_URL=https://ecoindex.p.rapidapi.com        # Or your own server url
API_KEY=your-generated-api-key                     # Optional if not production server

# You can also specify your application listening port (default is 3001)
APP_PORT=1337

You need to launch a local redis server. The simpliest way to do so is to use a docker image of redis:

docker run -d -p 6379:6379 redis

Then you can launch your project simply using air command:

air

You can also use docker compose to launch the project:

cp docker-compose.yml.dist docker-compose.yml
docker-compose up -d --build && docker-compose logs -f

You can now reach your Back For Front instance on http://localhost:3001 (regarding the APP_PORT you defined...)

🔧 Configuration

Environment variables

Name Description Default value
API_URL The url of the ecoindex API you want to reach "https://ecoindex.p.rapidapi.com"
API_KEY The API key you want to use to reach the ecoindex API (if production server) ""
APP_PORT The port on which the application will listen 3001
APP_URL The url of the application "http://localhost:3001"
BADGE_VERSION The version of the badge you want to use (comes from Ecindex badge project) "v1"
CACHE_DSN The DSN of the Redis cache "localhost:6379"
CACHE_ENABLED If you want to serve API results from cache true
CACHE_TTL The time to live of the cache (in seconds) 604800 (1 week)
CDN_URL The base url of the CDN where the badge is hosted "https://cdn.jsdelivr.net/gh/cnumr/ecoindex_badge"
ECOINDEX_URL The url of the ecoindex website "https://www.ecoindex.fr"
ENV The environment in which the application is running (in dev mode, enables logging) dev

About caching

The application uses a Redis cache to store the results of the API calls (only for /ecoindexes* endpoints). It is enabled by default, but you can disable it by setting the CACHE_ENABLED environment variable to false.

The cache is set to expire after 1 week (604800 seconds). You can change this value by setting the CACHE_TTL environment variable.

Endpoints /badge, /redirect and /api/results provide a refresh parameter to force the cache to be refreshed. Those endpoints also add cache-control header set to public, max-age=604800 (1 week) to allow the browser to cache the response.

➤ API Reference

Get latest results info

GET /api/results/?url=https://www.mywebsite.com/my-page/

Get latest results parameters

Name Type Located in Description
url string query Required. This is the url of the page from which you want to retrieve the latest results
refresh boolean query Optional. If set to true, the cache will be refreshed

Get latest results responses

Code Description Model
200 There are results in the DB LatestResultResponse
400 The url is not valid String
404 There is no result for this page LatestResultResponse

Add a new analysis to the tasks queue

This is an alias of the ecoindex API Create a new task endpoint

POST /api/tasks
{
    "url": "https://www.mywebsite.com/my-page/",
    "width": 1920,
    "height": 1080
}

Get the result of a task

This is an alias of the ecoindex API Get the result of a task endpoint

GET /api/tasks/a7c3d264-62c6-4f45-b1db-51d7db31d085

Get the screenshot of a ecoindex result

This is an alias of the ecoindex API Get screenshot of a ecoindex result endpoint

GET /api/screenshot/a7c3d264-62c6-4f45-b1db-51d7db31d085

Get Api Health

GET /health

Get health response

Code Description Model
200 OK API is healthy String

Get Ecoindex badge

GET /badge/?url=https://www.mywebsite.com/my-page/

Get badge parameters

Name Type Located in Description
url string query Required. This is the url of the page from which you want to retrieve the latest results
refresh boolean query Optional. If set to true, the cache will be refreshed
theme string query Optional. light / dark. If not set, defaults to light

Get badge responses

Code Description Model
200 Badge of the result (format svg/xml) String
400 The url is not valid String

Redirect to ecoindex result page

GET /redirect/?url=https://www.mywebsite.com/my-page/

Get redirect parameters

Name Type Located in Description
url string query Required. This is the url of the page from which you want to retrieve the latest results
refresh boolean query Optional. If set to true, the cache will be refreshed

Get redirect responses

Code Description Model
303 Redirect to the result page String
400 The url is not valid String

Models

Result

Name Type Description
date string Date of the result
grade string Ecoindex result grade
id string Result UUID
nodes int Number of nodes in the DOM of the webpage
requests int Number of requests made by the webpage
score int Ecoindex result score
size int Size of the webpage
url string Page URL

LatestResultResponse

Name Type Description
count int Number of total results existing for this website
latest-result Result Latest result for this exact webpage
older-results Result[] Older results for the same webpage
other-results Result[] Other results tor this website

License

Contributing

Code of conduct