Take a role

PUT /<org_name>/<path>/<role_name>.role

Roles

A client can take, release, or read a role in their org. To take and to release a role, the client needs to specify a player by player_name, which is a virtual representation of the client at the service. The client can run multiple players for their application and can name them anything. For a new role, the client can set max_players, which is the number of players allowed to play the role at the same time. If the role exists, the take-role request must specify the same max_players.

A role comes to existence once a take-role request is served and stays in existence until the last player has gone, either because their playtime has expired, or because they explicitly release the role. There is no creation or deletion operation for roles.

Request

Example

PUT /<org_name>/<path>/<role_name>.role
Host: <service_address>
Authorization: <org_key>
Content-Type: application/json
{
  "player_name": <string>,
  "playtime_secs": <u32>,
  "max_players": <u32>,
  "client_unix_time_in_msecs": <u64>,
}

PUT /sample_org/nemmies/rolls/cooks.role
Host: beta.useast2.registry.dkplatform.io
Authorization: randomAlphaNumericString
Content-Type: application/json
{
  "player_name": "cook_3",
  "playtime_secs": 30,
  "max_players": 10,
  "client_unix_time_in_msecs": 1708110795000,
}

Param	Meaning
Authorization	The credential showing the client's permission for the request. It is the `org_key` of the org.
Host	The service address, such as "useast2.registry.dkplatform.io".
"player_name"	Any string that represents the client who wants to play the role. Different clients must use different values.
"playtime_secs"	Optional, number of seconds the player wants to play the role. Default: 10 seconds.
"max_players"	Max number of players allowed to play the role concurrently. For example, 1 means that the role is a mutex.
"client_unix_time_in_msecs"	Current timestamp at the client.
x-dk-org-time	A response header that shows the org_time after the request is executed.

Response

200 OK Content-Type: application/json x-dk-org-time: <u64> { "client_expiration_time_in_msecs": <u64>, }	Success, the role already exists. Expiration time of the player is added or updated.Client should stop using the role when reaching `client_expiration_time_in_msecs`.
201 CREATED Content-Type: application/json x-dk-org-time: <u64> { "client_expiration_time_in_msecs": <u64>, }	Success, a role is created with the client and the expiration from `playtime_secs`.Client should stop using the role when reaching `client_expiration_time_in_msecs`.
400 BAD REQUEST	Wrong format in the path, wrong/missing Content-Type, missing Authorization header, or Authorization header is empty.
404 NOT FOUND	There is no such org, the org has been flagged for deletion, or (for confidentiality concern) the authorization token is invalid.
409 CONFLICT x-dk-org-time: <u64> { "max_players": <u32>, "players": [<string>,], }	The role is being taken by different players, or the role has a different max_players setting.
500 INTERNAL SERVER ERROR	An unexpected error happened at the server. It is unsure if the request has been processed or not.
507 INSUFFICIENT STORAGE	The service does not have enough storage to handle the request.