192 lines
5.2 KiB
Markdown
192 lines
5.2 KiB
Markdown
My website's API, stores information about my self-hosted services, it also
|
||
allows me to publish news and updates about these services using an Atom feed
|
||
and it keeps track of visitor metrics.
|
||
|
||
This documentation contains information about all the available API endpoints.
|
||
All the endpoints can be accessed using the `/api` route.
|
||
|
||
## Version 1 Endpoints
|
||
|
||
Each version 1 endpoint, can be accessed using the `/v1` route.
|
||
|
||
All the endpoints return JSON formatted data.
|
||
|
||
### Errors
|
||
|
||
If any error occurs, you will get a non-200 response. And the JSON data will
|
||
have an `error` key, which will contain information about the error that
|
||
occured, in the string format. This is the only JSON key that will be set in
|
||
non-200 responses.
|
||
|
||
### Results
|
||
|
||
If no error occurs, `error` key will be set to an emtpy string (""). If the
|
||
endpoint returns any data, this will be stored using the `result` key. The
|
||
`result` have a different expected type and a format for each endpoint.
|
||
|
||
### Multilang
|
||
|
||
Some `result` formats may use a structure called "Multilang". This is a simple
|
||
JSON structure that includes one key for each supported language. The key is
|
||
named after the language it represents. Currently only supported languages are:
|
||
|
||
- English (`en`)
|
||
- Turkish (`tr`)
|
||
|
||
So each multilang structure, will have **at least** one of these keys.
|
||
|
||
Here is an example multilang structure:
|
||
|
||
```
|
||
{
|
||
"en": "Hello, world!",
|
||
"tr": "Merhaba, dünya!"
|
||
}
|
||
```
|
||
|
||
If a `result` field is using a multilang structure, it will be specified as
|
||
"Multilang" in the rest of the documentation.
|
||
|
||
### Administrator routes
|
||
|
||
The endpoints under the `/v1/admin` route, are administrator-only routes. To
|
||
access these routes you'll need to specfiy a password using the `Authorization`
|
||
header. If the password you specify, matches with the password specified using
|
||
the `API_PASSWORD` environment variable, you will be able to access the route.
|
||
|
||
### GET /v1/services
|
||
|
||
Returns a list of available services. Each service has the following JSON
|
||
format:
|
||
|
||
```
|
||
{
|
||
"name": "Test Service",
|
||
"desc": {
|
||
"en": "Service used for testing the API",
|
||
"tr": "API'ı test etmek için kullanılan servis"
|
||
},
|
||
"check_time": 1735861944,
|
||
"check_res": 1,
|
||
"check_url": "http://localhost:7001",
|
||
"clear": "http://localhost:7001",
|
||
"onion": "",
|
||
"i2p": ""
|
||
}
|
||
```
|
||
|
||
Where:
|
||
|
||
- `name`: Service name (string)
|
||
- `desc`: Service description (Multilang)
|
||
- `check_time`: Last time status check time for the service, set 0 if status
|
||
checking is not supported for this service/status checking is disabled
|
||
(integer, UNIX timestamp)
|
||
- `check_res`: Last service status check result (integer)
|
||
- 0 if the service is down
|
||
- 1 if the service is up
|
||
- 2 if the service is up, but slow
|
||
- 3 if the service doesn't support status checking/status checking is disabled
|
||
- `check_url`: URL used for service's status check (string, empty if none)
|
||
- `clear`: Clearnet URL for the service (string, empty string if none)
|
||
- `onion`: Onion (TOR) URL for the service (string, empty string if none)
|
||
- `i2p`: I2P URL for the service (string, empty string if none)
|
||
|
||
You can also get information about a specific service by specifying it's name
|
||
using a URL query named `name`.
|
||
|
||
### GET /v1/news/:language
|
||
|
||
Returns a Atom feed of news for the given language. Supports languages that are
|
||
supported by Multilang.
|
||
|
||
### GET /v1/metrics
|
||
|
||
Returns metrics about the API usage. The metric data has the following format:
|
||
|
||
```
|
||
{
|
||
"since": 1736294400,
|
||
"total": 8
|
||
}
|
||
```
|
||
|
||
Where:
|
||
|
||
- `since`: Metric collection start date (integer, UNIX timestamp)
|
||
- `total`: Total number of visitors (integer)
|
||
|
||
### GET /v1/admin/logs
|
||
|
||
Returns a list of administrator logs. Each log has the following JSON format:
|
||
|
||
```
|
||
{
|
||
"action": "Added service \"Test Service\"",
|
||
"time": 1735861794
|
||
}
|
||
```
|
||
|
||
Where:
|
||
|
||
- `action`: Action that the administrator performed (string)
|
||
- `time`: Time when the administrator action was performed (integer, UNIX
|
||
timestamp)
|
||
|
||
### PUT /v1/admin/service/add
|
||
|
||
Creates a new service. The request body needs to contain JSON data, and it needs
|
||
to have the JSON format used to represent a service. See `/v1/services/all`
|
||
route to see this format.
|
||
|
||
Returns no data on success.
|
||
|
||
### DELETE /v1/admin/service/del
|
||
|
||
Deletes a service. The client needs to specify the name of the service to
|
||
delete, by setting the URL query `name`.
|
||
|
||
Returns no data on success.
|
||
|
||
### GET /v1/admin/service/check
|
||
|
||
Forces a status check for all the services.
|
||
|
||
Returns no data on success.
|
||
|
||
### PUT /v1/admin/news/add
|
||
|
||
Creates a news post. The request body needs to contain JSON data, and it needs
|
||
to use the following JSON format:
|
||
|
||
```
|
||
{
|
||
"id": "test_news",
|
||
"title": {
|
||
"en": "Very important news",
|
||
"tr": "Çok önemli haber"
|
||
},
|
||
"author": "ngn",
|
||
"content": {
|
||
"en": "Just letting you know that I'm testing the API",
|
||
"tr": "Sadece API'ı test ettiğimi bilmenizi istedim"
|
||
}
|
||
}
|
||
```
|
||
|
||
Where:
|
||
|
||
- `id`: Unique ID for the news post (string)
|
||
- `title`: Title for the news post (Multilang)
|
||
- `author`: Author of the news post (string)
|
||
- `content`: Contents of the news post (Multilang)
|
||
|
||
Returns no data on success.
|
||
|
||
### DELETE /v1/admin/news/del
|
||
|
||
Deletes a news post. The client needs to specify the ID of the news post to
|
||
delete, by setting the URL query `id`.
|
||
|
||
Returns no data on success.
|