The External Access API allows commands to be issued into the system from an external server or service. The External Access system has a large quantity of access to users and user data.
You will require a Developer Key to be issued to your user account, contact Iain Maltz for this, and any instance you wish to interact with must grant your avatar external connection access to their instance
Note: This functionality has been simply “bolted on” to the existing infrastructure (Commands, Responses, etc) which made it a lot easier to implement and will stay “current” as an API going forwards (since it uses the core published API). If you need additional functionality it's probably quite easy to add and should be requested. Some responses may be useful to expand (e.g. awarding XP returns the current number of XP afterwards, or the ammount available, or when available, as a separate JSON element), and in other cases (interrogating information) custom JSON Response commands can be created (see the end).
I'm sure there's more to write here
All requests must be presented over HTTPS to the URL https://sl.coagulate.net/GPHUD/external and are JSON formatted POST blocks/responses. Each request has the following common fields:
developerkey
' (String), the developer key assigned to you (see External.GetDeveloperKey
)runasinstancename
(String), the name of the instance to run asrunasinstanceid
(Integer), the ID of the instance to run asrunasavatarname
(String) the “full avatar name” OR UUID to set as the “invoking (calling) avatar”runasavatarid
(Integer) the “internal avatar ID” to set as the “invoking (calling) avatar”. Takes precedence over the name (but still don't specify both, wastes time).runascharactername
(String)runascharacterid
(Integer)command
(String) the name of the API command to callcheckavatarpermission
(String) UUID (preferably) or Avatar Name to check (see below)Some fields are mandatory, some are optional, some you must complete one or the other.
External.ConnectObjects
, this can be used where you have privileged in-world objects that would benefit from making use of GPHUD's access controls. An instance owner will have all permissions and thus this permission by default, and the instance owner can grant/revoke it from other avatars, for their instance only, at their leisure.
If the checkAvatarPermission field is not supplied, no check against External.ConnectObjects
will be made, this is the typical use case for the External interface where it assumed that authorisation and authentication have been performed by the external system. If the avatar passed in the checkavatarpermission field does not have the External.ConnectObjects
permission an Error response will be returned of responsetype UserException with error class “ExternalInterfaceObjectAccessDeniedException” (see example below)
Note that permissions checks are “normally” enforced, that is, if you try “runasavatar” a command that user doesn't have permissions for, you will get a permissions error. The SYSTEM user has full access to all permissions, so this may be appropriate for administrative operations.
In these examples (against the Development environment) we use “curl” to do the simple HTTP POST/Response part ; you probably want a JSON API and a HTTPS library for your own applications.
Responses can be distinguished by their “responseType”, so an OKResponse signifies success and probably contains a “message”, an ErrorResponse should contain an “error”.
If you botch the request badly you may be given a “terminate” string response ; this indicates you should discontinue your queries until you resolve the (otherwise permanent) failure, e.g. an incorrect developer key
curl https://sl.coagulate.net/GPHUD/external -d '{ "developerkey":"test2" , "applicationname":"Demo Application" , "command":"external.status" , "runascharactername":"test989" , "runasinstanceid":15 }'
Response:
{ "terminate": "Developer key is not known", "responsetype": "TerminateResponse" }
If something internally fails with an error inside GPHUD, and the error is of a “User” nature, it will be reported as an error string along with the class of the error. For “System” errors you'll only get the generic “Sorry, an internal error occured!” message. All exception reports are logged to developers for their review, and eventually some Exception cases are downgraded to Error cases once they're considered suitably normal.
curl https://sl.coagulate.net/GPHUD/external -d '{ "developerkeyy":"test" , "applicationname":"Demo Application" , "command":"external.status" , "runascharactername":"test989" , "runasinstanceid":15 }'
Response
{ "errorclass": "UserInputEmptyException", "error": "No developer credentials were supplied in the request", "responsetype": "UserException" }
If you are using the checkAvatarPermission field, you may get an access denied error, which you can use to tell the invoking user to go away (shut their connection, etc), it can be identified by the unique error class “ExternalInterfaceObjectAccessDeniedException” e.g.
curl https://sl.coagulate.net/GPHUD/external -d '{ "developerkey":"test" , "applicationname":"Demo Application" , "runasinstanceid":15 , "command":"experience.award" , "target":"iain" , "type":"xp" , "ammount":"1" , "reason":"Demonstration only" , "checkavatarpermission":"kate burner"}'
Response
{ "errorclass": "ExternalInterfaceObjectAccessDeniedException", "error": "User Kate Burner does not have permission External.ConnectObjects at instance DEV Test[#15]", "responsetype": "UserException" }
Sometimes operations fail for non-exceptional reasons, in this case just an “error” message would be returned. These are not mailed to developers as they're user induced errors rather than anything failing.
curl https://sl.coagulate.net/GPHUD/external -d '{ "developerkey":"test" , "applicationname":"Demo Application" , "runascharactername":"test989" , "runasinstanceid":15 , "command":"experience.award" , "target":"test989" , "type":"xp" , "ammount":"1" , "reason":"Demonstration only"}'
Response
{ "error": ">>> ERROR : award errored: \n--- This character has already reached their xp XP limit. They will next be eligable for a point in in 13h24m", "responsetype": "ErrorResponse" }
When an operation succeeds, most of the time you will just get a “message” prefixed by OK, this is the standard response the HUD gives.
curl https://sl.coagulate.net/GPHUD/external -d '{ "developerkey":"test" , "applicationname":"Demo Application" , "runascharactername":"test989" , "runasinstanceid":15 , "command":"experience.award" , "target":"test989" , "type":"xp" , "ammount":"1" , "reason":"Demonstration only"}'
Response
{ "message": "OK : Awarded 1 xp to test989", "responsetype": "OKResponse" }
Or:
curl https://sl.coagulate.net/GPHUD/external -d '{ "developerkey":"test" , "applicationname":"Demo Application" , "command":"notes.avatar" , "runascharactername":"test989" , "runasinstanceid":15 , "target":"Iain Maltz" , "note":"This is a note from the external interface"}'
Response
{ "message": "OK : Admin only avatar note added.", "responsetype": "OKResponse" }
Finally, some commands, particularly those built explicitly for External connections, will return a full fledged JSON response, these are mostly interrogative commands:
curl https://sl.coagulate.net/GPHUD/external -d '{ "developerkey":"test" , "applicationname":"Demo Application" , "command":"external.status" , "runascharactername":"test989" , "runasinstanceid":15 }'
Response
{ "nodename": "Saturn", "environment": "DEVELOPMENT", "character": "test989[#163]", "instance": "DEV Test[#15]", "sourcename": "Demo Application", "avatar": "SYSTEM[#11]", "sourcedeveloper": "Kate Burner[#12769]", "responsetype": "JSONResponse", "sourceowner": "Kate Burner[#12769]" }
This command allows an avatar to be resolved into contextual information about their login:
curl https://sl.coagulate.net/GPHUD/external -d '{ "developerkey":"test" , "applicationname":"Demo Application" , "command":"external.lookupAvatar" , "user":"Iain Maltz" , "runasinstanceid":15 }'
Response
{ "avatarid": 1, "playingcharactername": "test", "avatarname": "Iain Maltz", "playingcharacterid": 103, "responsetype": "JSONResponse", "playingcharacterregion": "Cerasi", "playingcharacterzone": "goodies base" }
Or, if the avatar isn't currently detected as being logged in, you'll get an error from the Avatar→Character lookup:
{ "error": ">>> ERROR : lookupAvatar errored: \n--- Avatar Iain Maltz is not wearing the HUD or is not logged in as a character presently.", "responsetype": "ErrorResponse" }
Note that all requests are logged in the system's console logs. Events that generate an Auditing event will be logged in the log against the sourceavatar/sourcecharacter e.g.
Note that hovering the mouse over the [Via] will generate a popup display of the accessing application's name, the developer key used, and 'also your originating IP address
'
Many of these are esoteric and unlikely to be of interest to External access developers.