Home
The KerbalX API is a mod dependency that can enable your mod to access KerbalX.com.
In order for your mod to use the KXAPI you first need to request API access. Email KerbalX Support or message Katateochi on the KSP forums
Once your mod has been accepted you'll be able to connect to KerbalX.com with KXAPI.
Put this line at the end of your AssemblyInfo.cs file to tell KSP that your mod depends on KXAPI:
[assembly: KSPAssemblyDependency("KXAPI", 1, 0)]Then add KXAPI to your the references.
To use the API you need to create an instance of the API and supply your mod's name and version. Add this class to your project:
using System;
using UnityEngine;
using KXAPI;
namespace MyMod
{
internal class KerbalX
{
internal static KerbalXAPI api = new KerbalXAPI("My Mod", "1.2.3");
}
}During development and testing of your mod you can interact with the KerbalX stage server (https://kerbalx-stage.herokuapp.com) so you can try things out without touching the production instance and data.
To tell KXAPI to use the stage server create a blank text file in the KXAPI directory and rename it to mode=testing. That's it; KXAPI will now send requests to stage.
Your mod does not need to do anything to collect or handle KerbalX usernames/emails, passwords or authentication tokens. That is all handled by KXAPI.
You can prompt a login by calling:
KerbalX.api.login();This can be done at any point during or after Start() in the MonoBehaviour sequence of events.
If the user has not ever logged in, then this will cause a login interface to be displayed. If the user has previously logged in (and has a KerbalX.key token file in their KSP root) then this will authenticate the token (without showing a login UI). If the token is no longer valid then the login UI will be displayed.
On all scenes except the main menu the login UI is a modal dialog (left). If login is called while on the main menu scene the UI is slightly different (right) and will always be shown (but will be retracted to one side if the user's token has been authenticated).
If the user has been logged in, the login UI will always be shown on the main menu scene, as this provides the user the option to logout.
login() can be given a callback method (delegate), which will be called once the user has completed logging in. The callback is passed a bool variable which is set to true if login has been successful and false if login has be cancelled. Note: the callback is only called with a false argument if the user cancels the login process, it is not called if they enter incorrect login details. The user can keep trying to login until they succeed (callback(true)) or cancel (callback(false)).
namespace MyMod
{
[KSPAddon(KSPAddon.Startup.MainMenu, false)]
internal class MyModMainMenu : MonoBehaviour
{
private void Start(){
KerbalX.api.login((login_successful) => {
if(login_successful){
Debug.Log("horray! I logged in");
}
});
}
}
}KerbalX.api.logged_in returns a bool; true if the user is logged in, otherwise false
KerbalX.api.logged_outreturns a bool; true if the user is logged out, otherwise true
KerbalX.api.logged_in_asreturns a string with the logged in user's username (if not logged in, returns null)
You don't actually need to call login(). If the user is not logged in, when you make a request on the API the login process will be triggered and once it has completed the initial request will be processed.
For example, in the following code test_connection is called on the API. If the user is not logged in, the request to /test_connection is stored and the login process takes over. Once the user has been logged in, the initial request to /test_connection is resumed. If the user was already logged in the request to /test_connection would take place right away.
KerbalX.api.test_connection((response, status_code) => {
//code here is called after the user has been logged in and the request to /test_connection has returned.
});Most api methods take a callback as their argument. The RequestCallback is a delegate with a string and an integer as arguments, and it will be called when the KerbalX server returns a response. The first <string> argument is the text response from the server, in most cases a JSON string. The second <integer> argument is the HTTP status code of the response, which if everything is OK will be 200. See HTTP status codes if you are unfamiliar with these.
KerbalX.api.test_connection((response, status_code) => {
if(status_code == 200){
Debug.log(response);
}else{
Debug.log("Something went wrong");
}
});As the above example shows, the status_code argument can be used to handle errors for each request. If you get a status code other than 200 then either an error or a failed validation has occurred.
The key status codes to watch for are 200 (OK), 400 (Incomplete/Bad request) and 422 (Unprocessable request) The latter two only apply when making a request which creates a database entry on the server (PUT/POST requests).
All other status codes are considered error codes.
KerbalX.api.failed_to_connectWill be true if the API is unable to connect to KerbalX (ie network issue or if the site is down).
KerbalX.api.server_error_messageWill contain an error message string if any error status code has been returned, otherwise it will be null.
KerbalX.api.upgrade_requiredwill be true if the API needs to be updated.
KerbalX.api.has_errors Will be true if any of the above are true/populated, and KerbalX.api.show_errors() will display a UI dialog with the error message.
So you can add this to your OnGUI() method to catch and display any errors:
if(KerbalX.api.has_errors){
KerbalX.api.show_errors();
}see sub sections for their API methods