Documentation: Create iTwin Share API page - default expiry is in the past

[r-veenstra]

The Create iTwin Share page is useful for generating keys by visiting https://developer.bentley.com/apis/access-control-v2/operations/create-itwin-share/ and clicking try it out.

By default, the request body is populated with a date set in the past. This causes the request generation to fail unless the user manually updates the date, or removes the request body altogether (defaulting to the max expiry)

Could we have one of these behaviours instead?

a) Have the request body be blank and rely on the maximum expiry to be generated automatically
b) Show the request body with a date, but update the date to be the maximum expiry rather than one in the past

[pbell97]

You're right, this is kind of problematic if people are just testing around in the Dev portal. I don't think the constraints of the APIM documentation allow us to dynamically update the date with the maximum expiry. However I can update the sample body to avoid this. Removing it all together would technically work, but for the sake of having people realize that a schema for the body exists it might be better to include both properties - the shareContract which is 'Default' and the expiration which can be marked as null.

{
    "shareContract": "Default",
    "expiration": null
}

[r-veenstra]

@pbell97 I think that approach makes sense, good call on keeping the schema there.

One question though is could null mislead users into thinking it is possible to have a no-expiry token?

A second question, is do we want to be directing users to this page for actual generation of share keys? I find it far more convenient to get a quick share key this way than to use postman, curl, etc, and had planned on directing users here in a Cesium tutorial I'm producing.

[pbell97]

I guess some users might think null would mean there is no expiration, however the immediate response to the request includes the actual expiration for the created share. That combined with the documentation on the page detailing that if an expiration is not provided then it defaults to the maximum expiration of 90 days I would hope it would be clear to the user what was expected.

To answer your second question - I don't think it is wrong to have users create their share keys via this page, especially if they are following a tutorial. However, like most APIs in the iTwin platform, this endpoint was designed with service-to-service or app-to-service calls in mind, so we would assume developers would be understanding the documenation to properly write code to make the http requests. But I do understand that users following cesium tutorials come from a much broader range of backgrounds and aren't necessarily always branded as 'developers'. So your call on that would be better than mine.