diff --git a/Web-API-Spec.md b/Web-API-Spec.md new file mode 100644 index 0000000..7577fed --- /dev/null +++ b/Web-API-Spec.md @@ -0,0 +1,118 @@ +To implement authentication and other features, you will need to provide some API endpoints in your web application. Here are some examples of the kinds of requests and responses you'll need to handle. + +## Authenticate a user +The following server configuration values are required to use authentication. The URL should be set to the appropriate API endpoint for your application. +``` +[LoginServer] +useExternalAuth=true +externalAuthURL=http://example.com/api/auth +``` + +Optionally, you can specify how the request will be made. JsonWebApi is recommended. You can also set a secret key that will be sent with each request so that you can confirm that the request is actually coming from your server. Using HTTPS is reccomended. +``` +useJsonWebApi=true +externalAuthSecretKey=somesuperdupersecretkey +``` + +If you have JsonWebApi enabled, whenever someone tries to log into SWG, the server will send a POST request to your AuthURL that looks like this: +``` +### Request +Content-Type: application/json + +{ + "user_name": "playsswgyodadoes", + "user_password": "securethisis", + "stationID": "123456", + "ip": "123.456.789.012", + "secretKey": "somesuperdupersecretkey" +} +``` +When your web application receives this request, you can authenticate the request with the secret key and then check the username and password against your users table. If you have systems for banning players, etc, this would be the time to check for that kind of stuff as well. If you want to log the IP and the Station ID of the user, you can do that too. Then, your application should send the response in JSON format. If you want to let the player in, `message` should be set to `success`. +``` +### Response +Content-Type: application/json + +{ + "message": "success" +} +``` +Otherwise, you can set message to anything you like and this will be displayed to the user as an error message in the swg client. +``` +### Response +Content-Type: application/json + +{ + "message": "Account does not exist or password was incorrect" +} +``` + +For the sake of completeness, if `useJsonWebApi` is set to false, The same values are passed as POST variables instead. This only affects the request. You should still form your response as JSON in the same way. + +### Admin Levels +You can have your SWG server fetch a user's admin level from your web application as an alternative to using an admin account datatable. (The admin level is typically a number between 0 and 50 to control how much access a user has to god mode on a server. 0 is none, 50 is everything. The specific capabilities for each admin level is beyond the scope of this document.) + +To do this, you need to set the following server configuration. The URL should be set to the appropriate API endpoint for your application. +``` +[ServerUtility] +externalAdminLevelsEnabled=true +externalAdminLevelsURL=http://example.com/api/adminlevel +``` +Optionally, you can set a secret key that will be sent with each request so that you can confirm that the request is actually coming from your server. Using HTTPS is reccomended. +``` +externalAdminLevelsSecretKey=somesuperdupersecretkey +``` +Now, when a player tries to `/setgod`, the server will send a POST request to your API. The username and (optionally) the secret key will be sent as POST variables. +``` +### Request +Content-Type: application/x-www-form-urlencoded + +user_name=playsswgyodadoes&secretKey=somesuperdupersecretkey +``` +You can then get the admin level for this user from your application and send it back as a stringified integer in JSON format like this: +``` +### Response +Content-Type: application/json + +{ + "message": "50" +} +``` + +### Server Metrics +You can configure your SWG server to periodically send some statistics about your server to your web application. This is useful for indicating whether your server is online and how many players are logged in. + +To do this, you'll need to set a few server configuration values. The URL should be the appropriate API endpoint for your application. The interval sets how often the server should send stats. +``` +[CentralServer] +metricsDataURL=http://example.com/api/metrics +webUpdateIntervalSeconds=5 +``` + +Optionally, you can set a secret key that will be sent with each request so that you can confirm that the request is actually coming from your server. Using HTTPS is reccomended. +``` +metricsSecretKey=somesuperdupersecretkey +``` + +Now, the server will send a JSON object at the set interval: +``` +### Request +Content-Type: application/json + +{ + "clusterName": "yourCluster", + "totalPlayerCount": "50", + "totalGameServers": "1", + "totalPlanetServers": "1", + "totalTutorialSceneCount": "1", + "lastLoadingStateTime": "456456", + "clusterStartupTime": "600", + "timeClusterWentIntoLoadingState": "0", + "webUpdateIntervalSeconds": "5", + "secretKey": "somesuperdupersecretkey" +} +``` + +You'll have to implement some of your own logic to infer the server's status: +* The server is offline if the last metrics update was recieved longer ago than `webUpdateIntervalSeconds` +* The server is loading if `lastLoadingStateTime == 0` +* The server is online if `timeClusterWentIntoLoadingState == 0` \ No newline at end of file