Previously, we released similar material on our main integration scripts KClient.php, KClient JS, and S2S postbacks. Today, it’s time to analyze the Admin API in detail: why the Admin API is needed, what cases this interface solves, and how to correctly form API requests to the tracker.
Admin API interface
The Application Programming Interface (API) describes how one computer program can interact with another program.
Keitaro Admin API is an interface that allows you to control the admin panel of the Keitaro tracker through incoming requests. That is, without going into the tracker admin panel, you can, for example, create a campaign with the necessary settings, change stream content, or generate a conversion report, whether it be through a server script or an external application like Postman.
Actual Application of the Admin API
The Admin API is often used when it is necessary to automate routine scripts or work with large amounts of data.
Example A
The client wants to download relevant conversions from the tracker every six hours and send the list to their CRM.
When working through the web interface, conversions will have to be downloaded manually. Then will have to convert the received report from CSV or Excel to the required format for CRM and send it manually.
The Admin API allows you to form a server request to receive the desired report, which can then be automatically parsed, converted, and sent to CRM. All this can be placed in one script file, which the scheduler will run every 6 hours, as specified in the condition.
Example B
Every 24 hours, the client receives a list of 100 domains that needs to be added to the tracker.
In manual mode, the list will need to be converted to a string, where each value must be separated by a separator. After that, add the domains to the tracker.
Using the Admin API, the list of domains will automatically be generated and can, by a server request, be added to the tracker. This task can also be executed according to a schedule or depending on a trigger event.
How do I use the Admin API?
For simple and convenient work with the Admin API, it is desirable to have at least basic skills in working with any of the server-side languages: PHP, Node, Python, etc. But if you wish, this interface can also be mastered by a technically inexperienced person.
In simple terms, the tracker has an entry point (a specific address) to which you send a request (the principle is similar to when you type a website address into your browser).
Then, depending on the specified request parameters, you receive one or another response.
To carry out this request and have it validated, you need to:
- Use an authorization key (roughly speaking, your password, which will prevent third-party users from receiving information).
- Use the correct query type.
- Set the required parameters (needed for requests to create entities, such as creating a campaign).
You can get the authorization key from inside the tracker in Service — Users — Key for Admin API.
As for the query type, the following set is used when working with the Keitaro Admin API:
GET — to get information, for example, a list of tracker campaigns:
https://keitarosupport1.xyz/admin_api/v1/campaigns
POST — for building reports, as well as for creating something, for example, a new campaign in the tracker:
https://keitarosupport1.xyz/admin_api/v1/campaigns
Please note that the request address looks the same outwardly: in both cases, we refer to the “tracker entry point,” which contains:
- tracker address — keitarosupport1.xyz
- the Admin API section — admin_api/v1/
- and then a specific subsection of the tracker, campaigns — campaigns.
The type of request must be specified when sending. For example, when using CURL, the queries look like this:
curl -X GET “https://keitarosupport1.xyz/admin_api/v1/campaigns” -H “accept: application/json” -H “Api-Key: 029e67361fc20e99ad02a8”
To create a campaign the query is:
curl -X POST “https://keitarosupport1.xyz/admin_api/v1/campaigns” -H “accept: application/json” -H “Api-Key: 029e67361fc20e99ad02a8” -H “Content-Type: application/json” -d “{\” alias\ “:\” alias\ “,\” type\ “:\” position\ “,\” name\ “:\” name\ “, ………\” url\ “:\” string\ “}]}”
PUT — to update the available data in the tracker.
DELETE — to delete data in the tracker.
We have now shown the keys and described the types of queries. It remains to view the parameters, and then you can practice making requests. Where can I get the list of required query parameters?
Refer to our documentation: https://admin-api.docs.keitaro.io
Find the type of request you want to make. There will also be a list of required parameters. For example, the list of parameters necessary for creating a campaign in the tracker includes alias and name.
You can create a campaign by setting only these two parameters. The rest of the campaign settings will be selected by default.
You can also get a ready-made example of the body (body) of the request, in which you only need to replace the stub values with your own, and you can use this code in your request (shown in the screenshot on the right).
How do I get started with Admin API?
If you’ve read this far and are eager to try your hand at building queries and running the Admin API, then the easiest way to get started is to use our Swagger documentation. It is an interface that combines our Admin API documentation and the ability to send genuine requests to the tracker.
Open Service — Users — Keys for Admin API, copy your key, and click on the Documentation tab. You will be transferred to interactive mode, where you can practice with queries.
First of all, let’s go through authorizations:
Select the desired section, for example, creating a campaign
and click Try it out. This will allow us to edit our query body, which will be sent when the Execute button is clicked. Inside this body, we set our required parameters name, alias, and any additional ones we want to specify when creating a campaign.
Click Execute and see our sent request, the request address, and the response from the tracker.
If the request returns an error, you will see a different response status, and the description of the error will be in the Response body field.
You can test any type of request until you get the hang of it and achieve the desired result with the Admin API.
More advanced users can try to work with the Admin API from a third-party application like Postman or write their own server-side script, which will send a request to the Admin API.
Watch our video guide on the formation of non-standard queries:
If you still have questions about working with the Admin API, you can always write to us in Support through the chat function on keitaro.io or through the Telegram bot. We will definitely help you figure it out.
