Difference between revisions of "RegAPI Documentation"

From Second Life Wiki
Jump to navigation Jump to search
(Redirecting to Registration API)
Line 1: Line 1:
It is recommended you start with the [[RegAPI|overview]], [http://secondlife.com/developers/third_party_reg/#what_are_cap create your capabilities], read  [[Using the RegAPI]], then go to [[RegAPI Documentation]],  [[RegAPI/Sample Code|Sample Code for RegAPI]] and [[RegAPI Tips]].
#REDIRECT [[Registration API]]
 
==What is LLSD XML?==
 
Use LLSD XML data format to send and get information to and from capability URLs. Here is 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, and so on. Each data type corresponds to a native object type in most languages.
 
The 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 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.
 
<b>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.</b> (See the section [http://secondlife.com/developers/third_party_reg/#what_are_cap 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 can be registered 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>
 
 
[[Category:RegAPI|Documentation]]
[[Category:Web Service APIs]]

Revision as of 10:35, 19 February 2009

Redirect to:

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