From d04b2051b2fe02874af6fde659be3dfd0907ccfd Mon Sep 17 00:00:00 2001 From: Zack Piispanen Date: Sun, 5 Apr 2015 17:44:27 -0400 Subject: [PATCH] Change static readonly fields in RestManager to const, as a const is a static readonly field, and allows us to use them in the rest documentation attributes. Added more documentation, as it might be useful to know what each argument is for, and what type it is expected to be. Documented the first block of rest commands. --- TShockAPI/Rest/RestManager.cs | 78 +++++++++++++++++++++++++------ TShockAPI/Rest/RestPermissions.cs | 38 +++++++-------- 2 files changed, 83 insertions(+), 33 deletions(-) diff --git a/TShockAPI/Rest/RestManager.cs b/TShockAPI/Rest/RestManager.cs index ad1db902..eefab0aa 100644 --- a/TShockAPI/Rest/RestManager.cs +++ b/TShockAPI/Rest/RestManager.cs @@ -31,6 +31,17 @@ using TShockAPI.DB; namespace TShockAPI { + [AttributeUsage(AttributeTargets.Method, AllowMultiple = true)] + public class Permission : Attribute + { + public string Name { get; set; } + + public Permission(string name) + { + Name = name; + } + } + [AttributeUsage(AttributeTargets.Method)] public class RouteAttribute : Attribute { @@ -42,30 +53,38 @@ namespace TShockAPI } } - [AttributeUsage(AttributeTargets.Method, AllowMultiple = true)] - public class Verb : Attribute + public class ParameterAttribute : Attribute { public string Name { get; set; } public bool Required { get; set; } + public string Description { get; set; } + public Type ArgumentType { get; set; } - public Verb(string name, bool req) + public ParameterAttribute(string name, bool req, string desc, Type type) { Name = name; Required = req; + Description = desc; + ArgumentType = type; } } [AttributeUsage(AttributeTargets.Method, AllowMultiple = true)] - public class Noun : Attribute + public class Noun : ParameterAttribute { - public string Name { get; set; } - public bool Required { get; set; } + public Noun(string name, bool req, string desc, Type type) : base(name, req, desc, type) { } + } - public Noun(string name, bool req) - { - Name = name; - Required = req; - } + [AttributeUsage(AttributeTargets.Method, AllowMultiple = true)] + public class Verb : ParameterAttribute + { + public Verb(string name, bool req, string desc, Type type) : base(name, req, desc, type) { } + } + + [AttributeUsage(AttributeTargets.Method)] + public class Token : Noun + { + public Token() : base("token", true, "The REST authentication token.", typeof(String)){} } public class RestManager @@ -146,10 +165,11 @@ namespace TShockAPI #region RestServerMethods - [Description("Executes a remote command on the server, and returns the output of the command.")] + [Description("Deprecated: Executes a remote command on the server, and returns the output of the command.")] [RouteAttribute("/v2/server/rawcmd")] - [Noun("cmd", true)] - [Noun("token", true)] + [Permission(RestPermissions.restrawcommand)] + [Noun("cmd", true, "The command and arguments to execute.", typeof(String))] + [Token] private object ServerCommand(RestRequestArgs args) { if (string.IsNullOrWhiteSpace(args.Parameters["cmd"])) @@ -167,6 +187,11 @@ namespace TShockAPI return RestResponse(string.Join("\n", tr.GetCommandOutput())); } + [Description("Executes a remote command on the server, and returns the output of the command.")] + [RouteAttribute("/v3/server/rawcmd")] + [Permission(RestPermissions.restrawcommand)] + [Noun("cmd", true, "The command and arguments to execute.", typeof(String))] + [Token] private object ServerCommandV3(RestRequestArgs args) { if (string.IsNullOrWhiteSpace(args.Parameters["cmd"])) @@ -187,6 +212,13 @@ namespace TShockAPI }; } + [Description("Turn the server off.")] + [Route("/v2/server/off")] + [Permission(RestPermissions.restmaintenance)] + [Noun("confirm", true, "Required to confirm that actually want to turn the server off.", typeof(bool))] + [Noun("message", false, "The shutdown message.", typeof(String))] + [Noun("nosave", false, "Shutdown without saving.", typeof(bool))] + [Token] private object ServerOff(RestRequestArgs args) { if (!GetBool(args.Parameters["confirm"], false)) @@ -199,6 +231,13 @@ namespace TShockAPI return RestResponse("The server is shutting down"); } + [Description("Attempt to restart the server.")] + [Route("/v3/server/restart")] + [Permission(RestPermissions.restmaintenance)] + [Noun("confirm", true, "Confirm that you actually want to restart the server", typeof(bool))] + [Noun("message", false, "The shutdown message.", typeof(String))] + [Noun("nosave", false, "Shutdown without saving.", typeof(bool))] + [Token] private object ServerRestart(RestRequestArgs args) { if (!GetBool(args.Parameters["confirm"], false)) @@ -211,6 +250,10 @@ namespace TShockAPI return RestResponse("The server is shutting down and will attempt to restart"); } + [Description("Reload config files for the server.")] + [Route("/v3/server/reload")] + [Permission(RestPermissions.restcfg)] + [Token] private object ServerReload(RestRequestArgs args) { TShock.Utils.Reload(new TSRestPlayer(args.TokenData.Username, TShock.Groups.GetGroupByName(args.TokenData.UserGroupName))); @@ -218,6 +261,10 @@ namespace TShockAPI return RestResponse("Configuration, permissions, and regions reload complete. Some changes may require a server restart."); } + [Description("Broadcast a server wide message.")] + [Route("/v2/server/broadcast")] + [Noun("msg", true, "The message to broadcast.", typeof(String))] + [Token] private object ServerBroadcast(RestRequestArgs args) { var msg = args.Parameters["msg"]; @@ -312,6 +359,9 @@ namespace TShockAPI return ret; } + [Description("Test if a token is still valid.")] + [Route("/tokentest")] + [Token] private object ServerTokenTest(RestRequestArgs args) { return new RestObject() diff --git a/TShockAPI/Rest/RestPermissions.cs b/TShockAPI/Rest/RestPermissions.cs index 5b8c765d..6f005c12 100644 --- a/TShockAPI/Rest/RestPermissions.cs +++ b/TShockAPI/Rest/RestPermissions.cs @@ -25,66 +25,66 @@ namespace Rests // tshock.rest.bans nodes [Description("REST user can list and get detailed information about bans.")] - public static readonly string restviewbans = "tshock.rest.bans.view"; + public const string restviewbans = "tshock.rest.bans.view"; [Description("REST user can alter bans.")] - public static readonly string restmanagebans = "tshock.rest.bans.manage"; + public const string restmanagebans = "tshock.rest.bans.manage"; // tshock.rest.groups nodes [Description("REST user can list and get detailed information about groups.")] - public static readonly string restviewgroups = "tshock.rest.groups.view"; + public const string restviewgroups = "tshock.rest.groups.view"; [Description("REST user can alter groups.")] - public static readonly string restmanagegroups = "tshock.rest.groups.manage"; + public const string restmanagegroups = "tshock.rest.groups.manage"; // tshock.rest.users nodes [Description("REST user can list and get detailed information about users.")] - public static readonly string restviewusers = "tshock.rest.users.view"; + public const string restviewusers = "tshock.rest.users.view"; [Description("REST user can alter users.")] - public static readonly string restmanageusers = "tshock.rest.users.manage"; + public const string restmanageusers = "tshock.rest.users.manage"; [Description("REST user can get user information.")] - public static readonly string restuserinfo = "tshock.rest.users.info"; + public const string restuserinfo = "tshock.rest.users.info"; // Non-grouped nodes [Description("User can create REST tokens.")] - public static readonly string restapi = "tshock.rest.useapi"; + public const string restapi = "tshock.rest.useapi"; [Description("User or REST user can destroy all REST tokens.")] - public static readonly string restmanage = "tshock.rest.manage"; + public const string restmanage = "tshock.rest.manage"; [Description("REST user can turn off / restart the server.")] - public static readonly string restmaintenance = "tshock.rest.maintenance"; + public const string restmaintenance = "tshock.rest.maintenance"; [Description("REST user can reload configurations, save the world and set auto save settings.")] - public static readonly string restcfg = "tshock.rest.cfg"; + public const string restcfg = "tshock.rest.cfg"; [Description("REST user can kick players.")] - public static readonly string restkick = "tshock.rest.kick"; + public const string restkick = "tshock.rest.kick"; [Description("REST user can ban players.")] - public static readonly string restban = "tshock.rest.ban"; + public const string restban = "tshock.rest.ban"; [Description("REST user can mute and unmute players.")] - public static readonly string restmute = "tshock.rest.mute"; + public const string restmute = "tshock.rest.mute"; [Description("REST user can kill players.")] - public static readonly string restkill = "tshock.rest.kill"; + public const string restkill = "tshock.rest.kill"; [Description("REST user can drop meteors or change bloodmoon.")] - public static readonly string restcauseevents = "tshock.rest.causeevents"; + public const string restcauseevents = "tshock.rest.causeevents"; [Description("REST user can butcher npcs.")] - public static readonly string restbutcher = "tshock.rest.butcher"; + public const string restbutcher = "tshock.rest.butcher"; [Description("REST user can run raw TShock commands (the raw command permissions are also checked though).")] - public static readonly string restrawcommand = "tshock.rest.command"; + public const string restrawcommand = "tshock.rest.command"; [Description("REST user can view the ips of players.")] - public static readonly string viewips = "tshock.rest.viewips"; + public const string viewips = "tshock.rest.viewips"; } }