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": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://api.vpsbg.eu/v1/servers?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "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.

Last modified: 3 months ago