who needed it and how we made it
Then we decided to take a different path: completely separate the black box that works with all our services, give it an external API and connect clients to it. This approach later helped us to separate a separate client tool from the control panel – the API.
The architecture of the project was initially laid out correctly: the backend layer was separated and not connected to the frontend part, which means the client could be absolutely anything. In order to call the API, you can use different transports: HTTP and a message broker on RabbitMQ. And each service layer has effective unit test coverage.
API for clients
We started working on a dedicated API after several dozen requests for a mobile application from clients. The application needed a universal interface that would allow access to all services at once, so we also decided to implement the task through the API.
The API for the control panel was used as a basis. At the same time, we understood that some methods needed to be refactored and changed in terms of the number of parameters, because they may not be obvious to the client. For example, the Control Panel API has return values that are needed to display values. And some developer will not need them.
It was important to make the public API so that it would not be tailored only to our company and our control panel, but would be useful to a wide range of developers. This was the main difficulty in adapting the public API.
What technology was chosen for the SpaceWeb API?
To access the API, the HTTP/HTTPS protocol is used, and data is transmitted in the form of JSON-RPC using the POST method. The API method to be called is contained in the request along with the call parameters.
We chose JSON-RPC because it was important to separate the business logic layer from the protocol layer. Its advantage is that the response headers are read unambiguously for us and for the client. For example, if the response is 500, then this means there is a problem on the server side. If the response is 200, but the response contains a JSON-RPC error decryption, then this error is in the application, the business logic layer.
But in the Rest API, everything works differently. If an error occurs, a header with code 500 may arrive and it will not be clear to us: it was the server itself that crashed or the response from the API with error 500. That is, the transport and application logic is mixed here.
How the client API works
Authorization and token
In most cases, access to the API will require a token. You can receive it after authorization by sending a request to special url: https://api.sweb.ru/notAuthorized/. This request looks like this:
{
"jsonrpc": "2.0",
"method": "getToken",
"params": {
"login": "<ваш логин>",
"password": "<ваш пароль>"
}
}The token itself will be contained in the response in the result parameter:
{
"jsonrpc": "2.0",
"id": "20220505104244.40FxsQ16Ff",
"result": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}Request
To access the API it is requested separate url: https://api.sweb.ru/domains/. The request contains the following headers:
Content-Type: application/json; charset=utf-8
Accept: application/json
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxAll requests other than those addressed to public methods must contain the Authorization: Bearer authorization token.
The request body may look like:
{
"jsonrpc": "2.0",
"method": "move",
"params": {
"domain": "vpstest.ru"
},
"id": "20183994338.43VSEkfGFh",
"user": "xxxxxxxxx"
}This request has the following parameters:
jsonrpc is the current version of JSON-RPC. This is a required parameter.
method — method of the Domains object. If it is not passed, the system will assign a default method to the object.
params – object of method parameters (object element key – parameter name).
id — unique request identifier. If it is not contained in the request, then the id will be generated on the API side.
user — login of the user who is sending the request. It is for informational purposes only; it is checked against the session token value and, in case of discrepancy, results in an authorization error.
Answer
If the API request is processed successfully, the system returns the result in the form of JSON:
{
"jsonrpc": "2.0",
"id": "20183995523.MO4E9baKRr",
"result": {
"balance": {
"real_balance": 500,
"bonus_balance": 0
}
}
}The response contains the required parameters:
jsonrpc – current version of JSON-RPC;
version — current client version;
result — the result returned by the called method;
id is a unique identifier of the response; if it was in the request, it matches it.
If an error occurs while processing a request, the response form will be as follows:
{
"jsonrpc": "2.0",
"version": "0.1",
"id": "20183910121.UPNWsDxwmn",
"error": {
"code": -32601,
"message": "Object not found"
}
}Extended message about the results of the method
Some methods, in addition to a successful or unsuccessful response, must pass a custom message or data to the client. For such responses, the generic type ExtendedResult is used. Such answers look like this:
{
"jsonrpc": "2.0",
"id": "20183995523.MO4E9baKRr",
"result": {
"extendedResult": {
"code": 1,
"message": "Заявка #180047823 принята в работу",
"data": []
}
}
}
{
"jsonrpc": "2.0",
"id": "20183995523.MO4E9baKRr",
"result": {
"extendedResult": {
"code": 0,
"message": "Зона .child не поддерживается для регистрации",
"data": []
}
}
}Here code 1 means successful execution, and 0 means an error. And the data field (additional data object) can remain empty.
What data does the API provide access to?
The functions that the client can access after authorization are divided into several categories in accordance with business logic: shared hosting, VPS, domains, affiliate program, financial service. Inside each section there is also a hierarchical system of objects that combine several functions – individual methods.
Real API usage case
The main users of the API are webmasters who manage several accounts for different clients at once. This is a very convenient feature for them.
If there were no API, the work would look like this: you go to the control panel of one client, upload data (for example, about balance, domains and SSL with an approaching registration expiration date), and analyze it in a table. And if you need to look at the metrics of another client or compare them, you log out of the previous account and log into the next one. And so on several times.
The API allows you to reduce the time spent switching between accounts. Using technology, a webmaster can create his own script and attach it to his dashboard to see information from all accounts at once. For example, using the API it is convenient to monitor the end date of domain registration for all accounts at once.
Our API uses different methods for managing accounts; we described them in detail in documentation. One of the popular ones is https://api.sweb.ru/pay/ the index method, it provides information about the account balance, the number of domain bonuses, due to which you can renew and register domains for free, account status and the expected blocking date.
Example request for url: https://api.sweb.ru/pay
{
"jsonrpc":"2.0"
"id":"715670275654947.SpiAFUtJpx"
"method":"index"
"params":{}
}Sample answer:
{
"jsonrpc":"2.0"
"id":"715670275654947.SpiAFUtJpx"
"params":[
{
"balance":{
"real_balance":30
"bonus_balance":0
}
"auto_payment_enable":0
"isAutopaymentEnable":1
"domainBonuses":0
"status":"active"
"blockInfo":{
"days_date":"07.02.2023"
"days":0
"days_word":"дней"
}
"blockedMoney":0
"deferment":{
"show":false
"value":0
}
"edgeDate":"2022-11-14"
}
]
}An important part of our API is the ability for clients to manage their affiliate program. You can receive information about clients from the affiliate program, current balance, and set up referral sites.
For verified clients, methods are available with which you can create separate accounts for attracted clients – createOrderVh, checkLogin, createOrderVip and others.
Using them, you can create a registration form with which, without going to the SpaceWeb website, you can register for virtual hosting or VPS. And the created account will be automatically connected to the affiliate program. Our competitors don't have this.
API development plans
First of all, we will expand the number of methods. Let's add mail and DNS management, methods for managing cloud platforms: balancer, database and backups. We will prepare open codes for clients – they can be integrated into any services.
We also want to introduce streaming data into the API, for example VPS snapshots. They weigh quite a lot, but we want to try to switch to a specification that supports the transfer of streaming data.
Do you use APIs when working with hosting providers? What methods are you missing?
