158 lines
5.1 KiB
Markdown
158 lines
5.1 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. The API itself is written in Go and uses SQLite for storage.
|
||
|
||
This documentation contains information about all the available API endpoints.
|
||
|
||
## 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.
|