Read a role

GET /<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

GET /<org_name>/<path>/<role_name>.role
Host: <service_address>
Authorization: <org_key>

GET /sample_org/nemmies/rolls/cooks.role
Host: beta.useast2.registry.dkplatform.io
Authorization: randomAlphaNumericString

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".
"max_players"	Max number of players allowed to play the role concurrently. For example, 1 means that the role is a mutex.
x-dk-org-time	A response header that shows the org_time after the request is executed.
"default_playtime_secs"	A response field showing the value to be used in a take-a-role request when the request does not provide a "playtime_secs".
"players_remaining_milliseconds"	A map from player names to their remaining playtime. A negative value means that the playtime has expired.

Response

200 OK x-dk-org-time: <u64> Content-Type: application/json { "default_playtime_secs": <u32>, "max_players": <u32>, "players_remaining_milliseconds": Map<string, i64>, }	Read returns the role policy and the remaining time of each player. Players that have expired playtime have negative remaining time. They will be lazily removed, when someone tries to take the role.
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, or (for confidentiality concern) the authorization token is invalid.
500 INTERNAL SERVER ERROR	An unexpected error happened at the server.