fix clean command and fix formatting for doc pages

Signed-off-by: ngn <ngn@ngn.tf>
This commit is contained in:
ngn
2025-07-24 14:09:21 +03:00
parent e3692f90b1
commit 8b0cf20bf2
5 changed files with 233 additions and 131 deletions

View File

@@ -1,52 +1,64 @@
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.
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.
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.
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.
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:
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.
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.
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:
Returns a list of available services. Each service has the following JSON
format:
```
{
"name": "Test Service",
@@ -62,73 +74,91 @@ Returns a list of available services. Each service has the following JSON format
"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_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
- 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`.
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.
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
"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)
- `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.
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`.
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",
@@ -143,7 +173,9 @@ to use the following JSON format:
}
}
```
Where:
- `id`: Unique ID for the news post (string)
- `title`: Title for the news post (Multilang)
- `author`: Author of the news post (string)
@@ -152,7 +184,8 @@ Where:
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`.
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.