Talk:WebKiosk/Rental Kiosks

From CasperTech Wiki
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Request for further documentation on the JSON API

Hi there! The JSON API for developers section presents the bare bones of the super-powerful JSON API, but without entering in many details, therefore I'm sort of requesting further documentation on it...

Firstly, at the time of writing (Feb 2024), the service starts responding with invalid JSON, namely, starting the connection by sending the extraneous string )]}',, which it clearly shouldn't. There is some kind of issue with the parser on your side, it's still emitting the trailing characters of the last request, and, as such, without jumping over them, any well-formed JSON parser will fail to decode the stream.

Secondly, I presume that there is only a way of retrieving parcels which are available for renting...? I'm asking this because the few experiments I made with https://www.casperpanel.com/api/rentals.php?accessKey=XXXX... always return the rentedBy field with NULL_KEY, while showing rentedUntil always set to zero, and, of course, the corresponding hideRented property is set to true. Is there a way to request hideRented to be set to false instead? I've tried with simple parameter passing — e.g. adding to the GET call ...&hideRented=false&hideAvailable=true, or 0 and 1, but none of these work. Attempting to use a POST call and adding those parameters as part of the request resulted in precisely the same output as before.

Is there any way to somehow authenticate yourself and unlock the ability of showing rented/reserved parcels as well?

Anyway, here is an example, and an attempt to document what each of these fields is supposed to do (slightly edited for privacy reasons): 

{
  "response": "OK",
  "availableUnits": [
    {
      "unitKey": "4f4df914-c8e7-4f3c-b5ee-6f0a52ffe6e5",
      "unitGroup": 45055,
      "unitName": "BaDoom P01",
      "ownerName": "BaDoom Resident",
      "ownerKey": "b8b35bcd-0ebb-4d3f-8662-91390b868c2c",
      "position": "<67.93, 159.88, 3001.31>",
      "unitX": 67,
      "unitY": 159,
      "unitZ": 3002,
      "unitXOverride": 108,
      "unitYOverride": 35,
      "unitZOverride": 23,
      "slurl": "secondlife://BaDoom/108/35/22",
      "paySlurl": "secondlife://BaDoom/68/160/3003",
      "region": "BaDoom",
      "regionOverride": "BaDoom",
      "prims": false,
      "regionX": 987654,
      "regionY": 999555,
      "price": 9999,
      "priceTerm": "Month",
      "rentedBy": "00000000-0000-0000-0000-000000000000",
      "rentedUntil": 0,
      "overLimit": false,
      "flags": 125187587,
      "locked": 0,
      "reservedFor": "00000000-0000-0000-0000-000000000000",
      "availableImage": "341c002a-7b48-4d7c-a44d-541eda15f2d8",
      "rentedImage": "",
      "description": "",
      "button1": 1,
      "button2": 2,
      "button3": 3,
      "button4": 4,
      "button1Units": "months",
      "button2Units": "months",
      "button3Units": "months",
      "button4Units": "months",
      "button1Months": false,
      "button2Months": false,
      "button3Months": false,
      "button4Months": false,
      "unitState": ""
    },
    {
      "unitKey": "66f85669-9172-4b65-b226-8f980b67f544",
      "unitGroup": 45055,
      "unitName": "BaDoom P02",
      "ownerName": "BaDoom Resident",
...
 ],
  "myRentalsAvailable": false,
  "rentedUnits": [],
  "myRentals": [],
  "hideRented": true,
  "hideAvailable": false,
  "currentSession": [],
  "__sessionID": "i3ouc9lj0hmaj0cj9zitlx9ukz"
}

Reference

Message header

response: (string)

Type of response from the API web service.
Example: "OK" if all goes well.

availableUnits: (array)

An array of all the units that are available for rental and not reserved.
Example: [].

Unit/Parcel fields

unitKey: (UUID)

UUID for this unit.
Question: is that the same UUID for the parcel or the Casper payment device?
Example: "4f4df914-c8e7-4f3c-b5ee-6f0a52ffe6e5".

unitGroup: (integer)

Probably a way of aggregating different units in a single group.
Question: is this user-configurable or generated by the system? Also, is there a way to retrieve unit group names — if they exist?
Example: 45055.

unitName: (string)

Name of the unit (conventionally, it's the parcel name, but that's not a requirement).
Example: "BaDoom P01".

ownerName: (string)

Name of the owner of this Casper device (legacy name format, with first name, space, and last name/Resident).
Note that this may not be the actual parcel owner (although usually it is), but rather the avatar who operates the rental business for this unit.
Example: "BaDoom Resident".

ownerKey: (UUID)

Avatar UUID of the owner described above.
Example: "b8b35bcd-0ebb-4d3f-8662-91390b868c2c".

position: (vector of floats)

In-world XYZ position of this parcel/unit (with decimal parts).
Example: "<67.93, 159.88, 3001.31>".

unitX: (integer)

X component of the position field above, converted to an integer.
Note: the rounding rules do not seem to be consistent.
Example: 67.

unitY: (integer)

See unitX.
Example: 159.

unitZ: (integer)

See unitX.
Example: 3002.

unitXOverride: (integer)

Unknown.
Possibly the X component of the unit/parcel's device allowing payment, if it is not the same as the unit/parcel position; or it might just be the actual teleport point, when it differs from the place where the parcel is (e.g., for a common "landing area").
Example: 108.

unitYOverride: (integer)

Unknown.
See unitXOverride comments.
Example: 35.

unitZOverride: (integer)

Unknown.
See unitXOverride comments.
Example: 23.

slurl: (URI)

SLURL for the parcel/unit, using a secondlife: prefix which can be used in-world to perform a direct teleport.
Example: "secondlife://BaDoom/108/35/22".

paySlurl: (URI)

SLURL for the place where the tier payment device is located.
Example: "secondlife://BaDoom/68/160/3003".

region: (string)

Region name, as shown on the Second Life Grid Map.
Possibly refers to the region where the payment device actually is.
Example: "BaDoom".

regionOverride: (string)

Unknown.
Possibly, like in previous fields, it refers to the region where the actual parcel/unit is located, when it's not thes same as where the tier payment device is.
Example: "BaDoom".

prims: (boolean)

Unknown.
Probably designates a "prim pool" area (as opposed to an actual parcel where the rentee can build their residence/shop, etc.).
Example: false.

regionX: (integer)

Global SL Grid coordinates, X component.
Unknown if it refers to region or to regionOverride.
Example: 987654.

regionY: (integer)

Global SL Grid coordinates, Y component.
Example: 999555.

price: (integer)

Value to be paid recurringly by the unit/parcel rentee.
Example: 9999.

priceTerm: (string)

Period of payment (i.e., how often the recurring payment has to be made).
Example: "Month".

rentedBy: (UUID)

UUID of the avatar currently renting this unit/parcel.
Will be NULL_KEY if the parcel isn't being rented.
Example: "00000000-0000-0000-0000-000000000000".

rentedUntil: (integer)

Time until which the unit/parcel is rented.
Note: since this is a JSON integer, one might argue that this is a Unix timestamp.
Zero (0) if the unit/parcel is currently not being rented.
Example: 0.

overLimit: (boolean)

Set to true if the rentee is delinquent in payment.
Example: false.

flags: (integer)

Unknown.
Very likely some sort of bit field.
It could be the object's permissions.
Example: 125187587.

locked: (integer)

Unknown.
Example: 0.

reservedFor: (UUID)

This unit/parcel is reserved for the avatar with this key (UUID), meaning that nobody else can rent it.
Example: "00000000-0000-0000-0000-000000000000".

availableImage: (UUID)

Texture UUID for showing when this unit/parcel is available.
Note that it can be retrieved using https://www.casperpanel.com/texture.php?uuid=<Texture UUID>; a smaller thumbnail can be retrieved via the SL Grid Picture Service.
Example: "341c002a-7b48-4d7c-a44d-541eda15f2d8".

rentedImage: (UUID)

Texture UUID for showing that this unit/parcel is currently being rented.
Also see comments for availableImage.
Example: "".

description: (string)

Description of this unit/parcel (shown on the web page and possibly elsewhere).
Can be left empty.
Example: "".

button1: (integer)

First button identifier.
Purpose unknown.
Example: 1.

button2: (integer)

See button1.
Example: 2.

button3: (integer)

See button1.
Example: 3.

button4: (integer)

See button1.
Example: 4.

button1Units: (string)

Time units for which the tier payment is valid, as shown by the first button.
Typically, these are in "months" or "weeks", but it's also possible to lease/rent by the day, or hour (for event venues, for example), etc.
Example: "months".

button2Units: (string)

See button1Units.
Example: "months".

button3Units: (string)

See button1Units.
Example: "months".

button4Units: (string)

See button1Units.
Example: "months".

button1Months: (boolean)

If set to true, the button period unit is a month.
False otherwise.
Probably useful for some code short-circuiting, since "month" may be considered the "default" rental period.
Example: false.

button2Months: (boolean)

See button1Months.
Example: false.

button3Months: (boolean)

See button1Months.
Example: false.

button4Months: (boolean)

See button1Months.
Example: false.

unitState: (string)

Unknown.
State in which this unit is in (?). Possibly may allow to identify broken payment devices or a period of time during which rent is not collected for some reason (e.g., the landowner temporarily claiming a vacant parcel for their own private use during a certain time).
Can be empty.
Example: "".

Other parameters

myRentalsAvailable: (boolean)

Unknown.
Example: false.

rentedUnits: (array)

Similar to the availableUnits array, but showing units currently being rented.
Example: [].

myRentals: (array)

Unknown.
Possibly related to a user-defined set of units/parcels?
Example: [].

hideRented: (boolean)

If true, hides all parcels currently being rented from the API response.
At the time of writing this, the mechanism to turn this to false is unknown.
Example: true.

hideAvailable: (boolean)

If true, hides all parcels currently available from the API response.
At the time of writing this, the mechanism to turn this to true is unknown.
Example: false.

currentSession: (array)

Unknown.
Example: [].

__sessionID: (string)

Unique 26-character string (lowercase + digits) that represents the session ID for this request.
Example: "i3ouc9lj0hmaj0cj9zitlx9ukz".

Feel free to use/reuse/complete/remove as necessary :)

— Gwyneth Llewelyn (talk) 12:38, 29 February 2024 (UTC)

Retrieved from "https://wiki.casperdns.com/index.php?title=Talk:WebKiosk/Rental_Kiosks&oldid=15436"