Talk:WebKiosk/Rental Kiosks

From CasperTech Wiki
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. — See Casper's comment below:

Hey - this is a security feature to avoid a potential JSONP exploit. All you need to do is trim the string before parsing. Please see https://docs.angularjs.org/api/ng/service/$http#:~:text=A%20JSON%20vulnerability%20allows%20third,before%20processing%20it%20as%20JSON for more info --D1cd5b71-6209-4595-9bf0-771bf689ce00 (talk) 18:17, 29 February 2024 (UTC)
Oh, thanks for the tip, Casper. I wasn't aware of this ancient vulnerability, although I suppose that the likelihood of anyone in 2024 still using FireFox 2.0 or IE 5 is rather remote... Granted, if Angular still does that stripping before parsing, it doesn't harm to continue to do the same. — Gwyneth Llewelyn (talk) 18:00, 1 March 2024 (UTC)
yes indeed. It wasn't so ancient at the time that CasperPanel was built (it's all in angularjs, version 1). Eventually it'll all be moved to CasperControl, a much more modern implementation, but for now I can't change this as people are already using it and trimming the characters. If I get rid of those it'll break existing users. --Casper Warden (talk) 19:51, 3 March 2024 (UTC)

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? — See comment below:

This endpoint just fetches the data from the kiosk profile as you've got it configured. You can change the profile to display rented units if you wish, then this endpoint will return those too. --D1cd5b71-6209-4595-9bf0-771bf689ce00 (talk) 18:17, 29 February 2024 (UTC)
Ah! That actually makes a lot of sense! — Gwyneth Llewelyn (talk) 18:00, 1 March 2024 (UTC)

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"
}

Hmm. Now I'm curious enough to warrant the development of a WordPress plugin that automatically fetches this and injects some sort of taxonomy into a website, so that we can do proper CSS styling :-) Stay tuned... or not...

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".
It's the UUID of the rental unit device. --Casper Warden (talk) 20:02, 3 March 2024 (UTC)

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.
The ID is auto generated but it corresponds with the unit group you've assigned on the website. --Casper Warden (talk) 20:02, 3 March 2024 (UTC)

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.
X and Y are rounded down. z is rounded up. This is too assist with teleports putting avatars through the floor. --Casper Warden (talk) 20:02, 3 March 2024 (UTC)

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.
Yes, the position override is an option on the website so you can configure a custom place to send users instead of directly onto the unit. --Casper Warden (talk) 20:02, 3 March 2024 (UTC)

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".
Again this is a user configurable override. --Casper Warden (talk) 20:02, 3 March 2024 (UTC)

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.
Yes, this is the land impact limit the unit is configured with --Casper Warden (talk) 20:02, 3 March 2024 (UTC)

regionX: (integer)

Global SL Grid coordinates, X component.
Unknown if it refers to region or to regionOverride.
Example: 987654.
The device region, not overridden --Casper Warden (talk) 20:02, 3 March 2024 (UTC)

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.
Yes, UNIX timestamp. More specifically, a 52 bit timestamp, compatible with JS, won't roll over in 2032 --Casper Warden (talk) 20:02, 3 March 2024 (UTC)

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.
Units can be locked to prevent payment. If set while rented, unit will be locked once the tenancy ends. --Casper Warden (talk) 20:02, 3 March 2024 (UTC)

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".
Please use the SL picture service directly. I can't assure that the CasperPanel one will always be available externally. --Casper Warden (talk) 20:02, 3 March 2024 (UTC)

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.
Number of time units to display on the payment button. e.g this would be 1 month.

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=15451"