Ping API

A small lightweight API, written in Rust for determining the state of remote web servers. It is developed as the Ping API of the /r/animepiracy index.

Getting started

The easiest way is to use docker via:

docker run -d -p <host-port>:5000 --name=pingapi ranimepiracy/pingapi

You'll need to change <host-port> to your port of choice. The web-server is not secured via SSL/TLS, it is in your responsibility to put a reverse proxy in front of this container.

Parameters

Here is a table of the possible ENV-variables with their default values.

Parameter	Function
`-e INTERVAL=300`	Time in s of when a known ping status is considered outdated and automatically refreshed
`-e TIMEOUT=10`	Timeout for ping requests
`-e CORS="https://piracy.moe"`	URL which uses this ping-api

Every 2 * TIMEOUT the background process will go through the list of known URLs to keep watch of and checks if their age is older than INTERVAL and if needed, updates the status with a new ping.

By default Ping API only allows requests from http://localhost and https://piracy.moe. You may want to overwrite CORS with the URL from which you intend to use the API.

API

Ping API supports only the following HTTP requests:

GET / will make a redirect to the URL provided by the env CORS
GET /health returns 200 OK
POST /ping returns a json-object of the following form:
```
{
"url": "https://piracy.moe",
"time": "1616615820",
"status": "up"
}
```
- url is the URL against which the ping has been tested
- time is the unix epoch timestamp in seconds
- status can be either up, down or unknown
It requires a json-object in the request body and Content-Type to be application/json. The body should be of the form:
```
{
  "url": "https://piracy.moe"
}
```

POST /pings returns a json-array of objects, which are of the same form as in /ping:

[{
  "url": "https://piracy.moe",
  "time": "1616615820",
  "status": "up"
},
...,
{
  "url": "https://example.com",
  "time": "1616615816",
  "status": "up"
}]

It requires a json-array of urls in the request body and Content-Type to be application/json. The body should be of the form:

{
  "urls": [
    "https://piracy.moe",
    "https://example.com"
  ]
}

Note: when you request a URL for the first time, it will always return an object like this:

{
  "url": "https://piracy.moe",
  "time": "0",
  "status": "unknown"
}

The background process will process it automatically and then update the values.

Updating container image

To get the newest version of image from docker-hub, you will need to run:

docker pull ranimepiracy/pingapi

Afterwards you will need to stop and remove your current running instance and start it again.

Building from source

To build the docker image you will need to run:

docker build . -t pingapi

Afterwards you will just need to run

docker run -d -p <host-port>:5000 pingapi

You can than open http://localhost:5000 in your browser.

Contribution

Pull-requests are always welcome, but may not be always merged as it has to be in align with our idea of the index. If you want a certain feature or have an idea, you can always open a feature request in Issues or report it on our Discord in #index to be discussed. If it is not bad, in align with our ideas, and we find some time, we will certainly implement your requested feature (sometime...).

What we use

to build this website:

Actix
redis

a1icja / pingapi