How to format `queues.json` file?

jjmaldonis commented 6 years ago

We want to provide a file with information about queues so that developers can automatically update their queues data without modifying code.

Below is the current idea for the format. In this issue I will try to summarize the discussion we've had about the format.

"Queue": {
  "id": int,
  "maps": List[int],
  "ranked": bool,
  "gameMode": str,
  "deprecated": bool,
  "name": str
}

Other relevant files might include: gameModes.json, gameTypes.json, seasons.json, and maybe a new maps.json file with additional information. Note that there are only three game types that Riot uses: CUSTOM_GAME, TUTORIAL_GAME, and MATCHED_GAME.

Notes about Queues:

The goal is to provide queue information to developers so they can automatically update their application using a request. We will provide a queues.json file via an API endpoint in CDragon.
We need to find the correct balance between providing enough information and being able to easily maintain that information. We have decided to provide a minimum amount of information to the consumer, but enough that is useful for the majority of use cases.
It's much easier to add information than it is to remove it. If we remove information in a file, it will break applications; if we add information, all consumers benefit.
The format for all files, including queues.json needs to be future-proof, meaning that it should be simple enough that expected changes to Riot's Queue data shouldn't break the format of the json data we provide.
We have opted for the naming scheme "Coop vs. AI" rather than "PvE"/"PvP" because very few game modes are truly player-vs.-environment. Coop vs. AI therefore captures the "competitive" vs. "non-competitive" natures of the different queues.
The "Coop vs. AI" vs. "Matched" naming schemes need to be applied to Queues rather than Game Modes because the game mode CLASSIC has queues that are both ranked and coop vs. AI. However, the rules of the game are properties of Game Modes rather than Queues.
We decided not to correlate deprecated queues with the new queues for a few reasons: 1) Some queues do not get replaced, and it's unclear where the line is for a "replaced" queue (for example, was Dominion replaced with Definitely Not Dominion, or is that a new queue? what about Ascension? The answer to these questions depends on the application.); 2) Because of (1), the syntax for parsing this information will not be obvious to the consumer; 3) The goal of this data would be to allow consumers to construct a list of queues that are all similar. It would be much simpler for us to just provide that information (a list of similar queues) rather than provide the "replaced with" logic, and it better supports the consumers' use case.
On that note, we will provide fields for each Queue that will allow the user to find ranked queues, 5v5 ranked queues, etc. We may also provide a separate endpoint with a list of queue ids for different categories of game modes (e.g. Ranked, Dominion, ARAM, etc).
Some APIs (including the Riot API) do not serve data that is equal to the default value. For example, 0s or False or null are often omitted to save on bandwidth. For this file (and for similar files), we prefer not to omit this type of "base" data because it makes the data harder to understand. For example, a consumer might wonder if a piece of data is omitted because it doesn't exist rather than because the value is zero.
The names that Riot assigns to their queues are not unique. We may come up with a better naming scheme ourselves. This is an excellent example of the tradeoff between maintainability and providing useful data. Hopefully any new naming scheme we develop can be generated from the fields of a Queue.
Below in a snippet from one of Pupix's gists that contains information about what Riot considers part of a Queue:

"QueueResource": {
    "properties": {
        "areFreeChampionsAllowed": { "type": "boolean" },
        "id": { "type": "integer" },
        "isRanked": { "type": "boolean" },
        "isTeamOnly": { "type": "boolean" },
        "mapId": { "type": "integer" },
        "minLevel": { "type": "integer" },
        "mode": { "$ref": "#/definitions/GameMode" },
        "numPlayersPerTeam": { "type": "integer" },
        "queueName": { "type": "string" },
        "type": { "type": "string" }
    },  
}

We have opted not to include information such as minLevel -- it's just too much information to keep track of without an automated way to extract it, and it isn't all that useful to consumers creating, for example, a web app.

We will try to maintain a TODO list in the comments.

jjmaldonis commented 6 years ago

TODO list:

Come up with a good naming scheme for queues.
Create a file with the list of similar queues.
Fix the TODOs for the game modes in the queues.json file

bbqtd commented 6 years ago

After rethinking the purpose of queues.json I think we should deprecate the field "deprecated": bool, there is several reasons:

as @jjmaldonis mentioned in https://github.com/CommunityDragon/Data/issues/1#issue-290207533 the file should be safe extendable;
So, for me it looks like patches.json that share common data. Queue object should be immutable. For consumer it means that values of a Queue object doesn't changeable in future but a new field could be add in next version (which means extendable).

That is why I think deprecated should not to be in Queue object because it breaks rule №2. Also if we guarantee immutability it should improve the strategy of updating cache for consumer.

The deprecated describes a status of a queue, while Queue should describes preset (configuration) of a game match. The value of deprecated is important but should be in some other place.

As one of the workaround could be "deprecated": [queue ids...], which works realy nice with partial cache update because there is only new values appends to the array.

bbqtd commented 6 years ago

The date of queue release

Regarding to https://github.com/CommunityDragon/Data/issues/1#issuecomment-359188679 I can suggest a field that correspond to the when a queue was released. The value of the field should be patch name. The consumer could retrieve the additional values from patches.json. Also, this extension doesn't break immutability.

"Queue": {
  "releasedAt": str // e.g. "7.24"
  ...
}

We can find a better name for this field.

Examples

getMatchlist
- As consumer, I want to find a game matches (with specified filters) since a time when a queue was released.
Comparing with other timestamps.

bbqtd commented 6 years ago

Rotating queue

As we know there are 2 types of queue:

Regular queue, like 420 (SR 5v5 Ranked Solo)
Rotating (temporary) queue, like 980 (Star Guardian Invasion: Normal)

I suggest a field that would describe this queue property. Something like "rotating": bool.

Why it is not related to the game mode?

For instance, let's look at 100 (Butcher's Bridge, ARAM). The queue is kind of rotating which game mode is ARAM. As we know, we have ARAM queue 450 that is regular. So we can consider that game mode can have both types.

Like mentioned in https://github.com/CommunityDragon/Data/issues/1#issuecomment-359188679 the property is kind of immutable.

bbqtd commented 6 years ago

Teams Identities (WIP)

Queue {
  teams: [{
    id: int,
    name: string,
    size: int,
  }],
  ...
}

The value is related to a queue because it describes the general game rule. Also, the value is immutable because a change has huge impact on old games that related to a queue. Each team has size which specifies number of players in a team.

Usage

With Riot API match and spectator endpoints.

wip...

bbqtd commented 6 years ago

The story about QueueID and zero value

Let's recap, there are 3 types of games:

MATCHED_GAME - is a game that has matchmaking. The matchmaking based on Queue that defines preset of game rules.
CUSTOM_GAME - is a game without matchmaking. There is no queue. The match creator has full access to define game rules and when to start the match.
TUTORIAL_GAME - is a single game without matchmaking and without access to setting game rules.

TL;DR no matchmaking - no queue.

Why QueueID 0 means the Custom Games?

Like I said before CUSTOM_GAME has no matchmaking which means no queue. It's 0 ID because it's zero value for numeric type. The Riot API don't ommit queue, queueId, and gameQueueConfigId field in responses. Instead, when there is CUSTOM_GAME or TUTORIAL_GAME they return zero value of numeric type for this fields which indicates there is no queue.

Conclusion

There is no queue with ID 0. It's zero value for int which indicates a CUSTOM_GAME or TUTORIAL_GAME type.

Restructuring

Deprecate Queue with 0 ID from list of queues.json;

Redesign Queue type. Without applying other proposals:

"Queue": {
  "id": int,
  "name": string,
  "gameMode": string, // before - "gameModes": []string
  "map": int,         // before - "maps": []int
  "ranked": bool,
  "deprecated": bool,
}

CommunityDragon / Data