RegAPI Documentation

From Second Life Wiki
Revision as of 03:30, 8 April 2008 by Xugu Madison (talk | contribs) (Added example uncaught error)
Jump to navigation Jump to search

It is recommended you start with the overview, create your capabilities, read Using the RegAPI, then go to RegAPI Documentation, Sample Code for RegAPI and RegAPI Tips.

What is LLSD XML?

LLSD XML is the data format you'll use to pass and get information to and from capability urls. Rather than explain it, heres an example of a typical LLSD XML message: 

<llsd>
  <map>
    <key>dob</key><string>1987-07-06</string>
    <key>start_region_name</key><string>da boom</string>
    <key>username</key><string>mistaht</string>
    <key>last_name_id</key><integer>1872</integer>
    <key>password</key><string>123456</string>
    <key>email</key><string>ben@ben.com</string>
  </map>
</llsd>

This document represents a Map (Hash) containing dob, start_region_name, username, last_name_id, password, and email as keys. This document is in fact a typical LLSD XML message that you might POST to the "create_user" capability url, in order to create a new user.

The LLSD specification specifies many different data types: Map, Array, String, Integer, Float, Date, etc. Each data type is corresponds to a native object type in most languages.

Our LLSD XML libraries handle almost all of the dirty work encoding native objects into LLSD XML and vice-versa. For example, the ruby library can be used the following way: 

require 'LLSD'

native_obj = 123
llsd_xml = LLSD.to_xml(native_obj) # returns <llsd><integer>123</integer></llsd>
returned_native_obj = LLSD.parse(llsd_xml) # returns native ruby integer, 123

As you can see, the libraries can do most of the work encoding and decoding LLSD XML. If you, however, are running into problems, looking at the actual LLSD XML being sent and received is always a good place to start debugging.


API Reference

The following are the details of each service.

Note, in order to gain the capability URL for each service, you'll need to POST your Second Life "first_name", "last_name", and "password" to https://cap.secondlife.com/get_reg_capabilities. (See the section What are Capability URLs.)

create_user (POST)

  • Creates a new Second Life user
  • POST to this url a LLSD XML document, representing a hash, containing at least "username" (string), "last_name_id" (integer), "email" (string), "dob" (string in YYYY-MM-DD format), "password" (string)
  • Optional arguments are "limited_to_estate" (integer), "start_region_name" (string), "start_local_x" (float between 0-128), "start_local_y", "start_local_z", "start_look_at_x" (float between 0-1), "start_look_at_y", "start_look_at_z"
  • If all is successful, a hash containing the new user's agent_id will be returned. If there are errors, instead an array containing the applicable error codes will be returned.

POST Parameters

Map

  • key: username
    • value (String): Desired username (i.e. SL first name). Between 2-31 alpha-numeric characters.
  • key: last_name_id
    • value (Integer): ID of desired SL last name.
  • key: email
    • value (String): Users email address.
  • key: password
    • value (String): Desired password. Between 6-16 characters.
  • key: dob
    • value (String): Users date of birth in the YYYY-MM-DD format.. Users under 18 cannot be registered to the mainland (see limited_to_estate)
  • limited_to_estate (not required)
    • value (Integer): ID of estate that the user will be limited to. Default is estate 1, the mainland. To change this to another estate, you must own the estate.
      • You can get the numeric estate ID via the debug menus (Ctrl+Alt+Shift+D to enable them). Then use Client > View Admin Options. This will allow you to view, but not use, the options that admins (Lindens) can use. Now go to the Server menu, which appeared with the Client one. Select God Tools, look at the Region tab... the Estate ID is listed there. Don't worry about pressing or changing something you shouldn't... as they are just viewable options, any changes you make won't stick. -- Spike Linden
  • start_region_name (not required)
    • value (String): Name of the region that the user will be initially teleported to. Default is the orientation island of the estate. This can only be set to simulators in the user's limited to estate.
  • start_local_x (not required)
    • value (Float): X coordinate of the region that the user will be teleported to.Between 0-256. Default is 128 (center). This parameter is ignored unless start_region_name is set.
  • start_local_y (not required)
    • value (Float): Y coordinate of the region that the user will be teleported to.Between 0-256. Default is 128 (center). This parameter is ignored unless start_region_name is set.
  • start_local_z (not required)
    • value (Float): Z coordinate of the region that the user will be teleported to.Between 0-256. Default is 128 (center). This parameter is ignored unless start_region_name is set.
  • start_look_at_x (not required)
    • value (Float): X component of the unit vector representing initial look direction.Between 0-1. Default is 0. This parameter is ignored unless start_region_name is set.
  • start_look_at_y (not required)
    • value (Float): Y component of the unit vector representing initial look direction.Between 0-1. Default is 1. This parameter is ignored unless start_region_name is set.
  • start_look_at_z (not required)
    • Currently z component is ignored (set to 0).

Return Value

Map - If user creation is sucessful, a map with the new user's information is returned

  • key: agent_id
    • value (Integer): ID of new SL user.

or

  • Array - If user creation fails, an array of error code(s) is returned.
    • Integer - Represents an error code (see get error codes)

Example Posted Message: 

<llsd>
  <map>
    <key>dob</key><string>1987-07-06</string>
    <key>start_region_name</key><string>da boom</string>
    <key>username</key><string>mistaht</string>
    <key>last_name_id</key><integer>1872</integer>
    <key>password</key><string>123456</string>
    <key>email</key><string>ben@ben.com</string>
  </map>
</llsd>

Example Reply Message: 

<llsd> 
  <map> 
      <key>agent_id</key> 
      <string>87cfdb64-c852-4359-ae16-dce36099ff68</string> 
  </map> 
</llsd>

get_last_names (GET)

Retrieves the names and ids of the last names you are able to register new users with

Example GET Response: 

<llsd> 
  <map> 
      <key>1926</key><string>Morellet</string> 
      <key>1683</key><string>Okamoto</string> 
      <key>1738</key><string>Rankin</string> 
... 
      <key>1870</key><string>Yang</string> 
  </map> 
</llsd>


check_name (POST)

Checks to see if a user already exists with a given Second Life first name and last name

POST the new user's desired "username" and "last_name_id", and you'll get back LLSD XML, representing a boolean. The same parameter restrictions for the "create user" service apply here.

Example Posted Message: 

<llsd> 
  <map> 
      <key>username</key><string>mistaht</string> 
      <key>last_name_id</key><integer>1872</integer> 
  </map> 
</llsd>

Example Reply Message: 

<llsd> 
  <boolean>true</boolean> 
</llsd>


get_error_codes (GET)

GET this url for an LLSD document describing what the error codes mean.

All the errors are in an array, and each error is, in addition, contained in an array. The first element in the array is the error code, the second is the name of the error, the third is the description.

Example GET Response: 

<llsd> 
   <array> 
       <array> 
           <integer>10</integer> 
           <string>invalid flow</string> 
           <string>The registration flow does not exist</string> 
       </array> 
       <array> 
           <integer>20</integer> 
           <string>missing required field</string> 
           <string>You are missing one of the required fields</string> 
       </array> 
... 
       <array> 
           <integer>1500</integer> 
           <string>malformed xml</string> 
           <string>Your xml is malformed</string> 
       </array> 
   </array> 
</llsd>

Errors

See RegAPI Error Codes for documentation on the error codes the RegAPI sends.

About Uncaught Errors

If something happened that can't be handled or caught, you'll get back a plain text message containing the error ticket of what caused this exception, for example: 

An fatal error has occurred (error ticket #12345). Please visit the support section at http://secondlife.com/support/ for further assistance.
Note this error ticket code and a description of the problem. Error Description: undefined method `permission' for #<User:0x00000000>.

If you get this error, please make note of what caused this, the error ticket number, and then email us.

Retrieved from "https://wiki.secondlife.com/w/index.php?title=RegAPI_Documentation&oldid=62432"