API Introduction
title: API Introduction
slug: x-BG-
description: Learn about the VPSBG API beta notice, which outlines the current state of the API and encourages user feedback. Discover how to make requests using various HTTP methods and understand the corresponding actions for each method. Explore the standard HTTP r
createdAt: 2023-10-18T08:42:56.078Z
updatedAt: 2024-01-03T14:18:47.150Z
🛠️ Beta Notice
🚧 This API is currently in Beta version! 🚧
Please note that while this API is in Beta, changes might occur without prior notice. We encourage you to use it cautiously and provide us with your valuable feedback to enhance its functionality and reliability.
Your insights will be highly valuable in improving the API and progressing out of Beta. Thank you for your understanding and cooperation!
🙋♂️ Introduction
The VPSBG API enables users to manage their services and other resources on the VPSBG's platform in a straightforward and programmatic manner, using standard HTTP requests. It uses standard HTTP response codes, verbs, and authentication mechanisms. The API features well-formed and consistent JSON requests and responses, with pagination that simplifies list management.
⚡ Requests
The API can be accessed by any HTTP client, simply by requesting the appropriate URI. Requests must be sent over HTTPS. The HTTP Method correspondents to the action.
METHOD | USAGE |
---|---|
GET | To fetch information about a resource, utilize the GET method, which returns the data in the form of a JSON object. GET methods are solely for read-only purposes and have no effect on any resources. |
POST | To create a new object, send a POST request using the required HTTP method. All necessary attributes should be included in the request body, which must be encoded as JSON. |
PATCH | Some resources support partial modification with PATCH, which modifies specific attributes without changing the rest. |
PUT | The PUT method is used to completely replace an existing resource or create a new one if it doesn't exist. When sending a PUT request, include all attributes necessary for the resource in the request body, encoded as JSON. |
DELETE | To delete a resource and remove it from both your account and environment, you should utilize the DELETE method. This will delete the specified object if it is present. If the object cannot be found, the operation will return a response indicating that it was not found. |
🔢 Response Codes
The API returns standard HTTP status codes to indicate whether a request was successfull or not. In the table below you can see all HTTP status code that this API might return.
RESPONSE | DESCRIPTION |
---|---|
200 OK | The requested information is provided. |
201 Created | Resource is created. |
202 Accepted | The resource was updated. |
204 No Content | Successful request, no response (not needed). |
401 Unauthorized | Not authorized (no valid token provided). |
403 Forbidden | You do not have access to this resource. |
404 Not Found | No results founds. |
422 Unprocessable Content | Validation error. |
423 Locked | The resource is locked at the moment. |
429 Too Many Requests | API rate limit exceeded. |
500 Internal Server Error | Server-side issue. |
✋ Rate limit
In order to ensure the smooth functioning of the API platform, we have implemented a rate limit per user. Currently, the limit is set at 200 requests per minute. If you exceed this limit, subsequent requests will result in a 429 HTTP error code until the start of the next cycle.
To make it easier for you to manage the rate limit, the following information is included in the response headers of each request:
- X-RateLimit-Limit
Indicates the maximum number of requests allowed within a minute. - X-RateLimit-Remaining
Shows the number of remaining requests you have before reaching the rate limit. - Retry-After
If you are already rate limited, this header specifies the time (in seconds) you need to wait before retrying your request. - X-RateLimit-Reset
If you are already rate limited, this header indicates the Unix epoch time when you can send your request again.
🗒️ Pagination and Links
When pagination is enabled, the response includes a data
array, along with links
and meta
objects that provide pagination details.
By default, 20 items are returned per page. You can customize this by appending ?per_page=
to your request URL with the desired number of items (maximum 100). For example: ?per_page=25
.
Links Object
The links
object provides URLs for navigating between pages:
first
: URL of the first page.prev
: URL of the previous page.next
: URL of the next page.last
: URL of the last page.
If a link isn't applicable (e.g., no previous page on the first page), its value will be null
.
Example
"links": {
"first": "https://api.vpsbg.eu/v1/servers?page=1",
"last": "https://api.vpsbg.eu/v1/servers?page=1",
"prev": null,
"next": null
}
Meta Object
The meta
object contains additional pagination information:
current_page
: Current page number.from
: Starting index of the items returned.last_page
: Total number of pages.links
: Pagination links.path
: Base URL.per_page
: Number of items per page.to
: Ending index of the items returned.total
: Total number of available items.
Example
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"links": [
{
"url": null,
"label": "« Previous",
"active": false
},
{
"url": "https://api.vpsbg.eu/v1/servers?page=1",
"label": "1",
"active": true
},
{
"url": null,
"label": "Next »",
"active": false
}
],
"path": "https://api.vpsbg.eu/v1/servers",
"per_page": 20,
"to": 1,
"total": 1
}
Controlling Pagination
Use the following query parameters to control pagination:
page
: Specify the page number. Example:?page=2
per_page
: Specify items per page. Example:?per_page=25
Example Request
GET http://api.vpsbg.eu/v1/servers?page=2&per_page=25
🚩 Permissions
When generating API tokens, users have the option to select permissions of type: read & write. It is important to note that if an API token is generated with only read permissions, it will only be able to make GET requests. In order to make other types of requests such as POST, PUT, PATCH, or DELETE, the API token must have the ability to write. It is worth mentioning that once an API token is generated with specific permissions, it cannot be changed and needs to be recreated if different permissions are required.