Group Match API

This is the API used for matching in groups, such as acquaintances or friends, during gameplay.

Before making a matching request, two or more app users must create a group, and the group representative will proceed with the matching request.

Create group¶

This is an API for creating a group to invite members to the same team.

• The creator of the request becomes the group leader (room leader).
• It cannot be used during personal matching requests.
• An entry code for inviting acquaintances is provided upon creation.
• When creating, score information can be entered to correspond to the rules of the match ID.

Request URL¶

Header parameters¶

Path parameters¶

Request body¶

Response¶

Request sample¶

curl --location 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/group' --header 'Content-Type: application/json' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a' --data '{"playerId":1}'

Response sample¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfos": [
        {
            "playerId": 1
        }
    ],
    "requestingStatus": "notRequested"
}

Join Group¶

This is the API used when app users who wish to join a group use the code (groupCode) received from the group leader (room leader) to participate in the group.

Request URL¶

Header parameters¶

Path parameters¶

Request body¶

Response¶

Request sample¶

curl --location 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/groups/code/0343322/member' --header 'Content-Type: application/json' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a' --data '{"playerId":2}'

Response sample¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1
        },
        {
            "playerId": 2
        }
    ],
    "requestingStatus": "notRequested"
}

Leave Group¶

This is the API used when you want to leave the group you are currently in. If the group leader (room leader) leaves, one of the remaining members will become the next group leader.

If there are no remaining members, the group will be removed.

Request URL¶

Header parameters¶

Path parameters¶

Response¶

In the case of 200 OK, the Body is empty.

Request sample¶

curl --location --request DELETE 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/players/2/group' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a'

Response sample¶

There is no special response content when processed normally.

Group Forced Ejection (Kick-out)¶

This is an API that allows the group leader (room leader) to forcibly expel a specific member.

요청 URL¶

헤더 매개변수¶

Path parameters¶

Response¶

This is the format of the result data for the group creation API. Only the information of members forcibly removed from the members' information (memberInfos) will be removed.

Request sample¶

curl --location --request DELETE 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/players/1/group/members/2' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a'

Response sample¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1
        }
    ],
    "requestingStatus": "notRequested"
}

Group Information Retrieval (Based on Group Members)¶

This is an API that retrieves information about the group to which the app user belongs at the time of the request. It can be used for various purposes, and it is necessary to periodically check through polling.

Usually used for the following purposes.

• Check the list of app users who joined the group
• Check the matching results after the matching request

Request URL¶

Header parameters¶

Path parameters¶

Response¶

Request sample¶

curl --location 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/players/1/group' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a'

Response sample¶

// 매칭 요청 전
{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1
        }
    ],
    "requestingStatus": "notRequested"
}
// 매칭이 성사된 이후 (2:2 팀전)
{
    "groupCode": "3683207",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1,
            "ready": true
        },
        {
            "playerId": 2,
            "ready": true
        }
    ],
    "matchingInfo": {
        "status": "matched",
        "matchingId": "2:1_2024-12-18T06:55:19.91_1",
        "teamInfos": [
            {
                "teamIndex": 0,
                "playerInfos": [
                    {
                        "playerId": 4,
                        "point": 50,
                        "extraData": "bbb"
                    },
                    {
                        "playerId": 3,
                        "extraData": "aaa"
                    }
                ]
            },
            {
                "teamIndex": 1,
                "playerInfos": [
                    {
                        "playerId": 1,
                        "extraData": "extra1"
                    },
                    {
                        "playerId": 2,
                        "point": 250,
                        "extraData": "aaa"
                    }
                ]
            }
        ]
    },
    "requestingStatus": "requested",
    "requestingInfo": {
        "requestTimeUtc": "2024-12-18T06:55:19.17"
    }
}
// 매칭 시간이 초과된 경우(timeout)
{
    "groupCode": "0400606",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1,
            "ready": true
        },
        {
            "playerId": 2,
            "ready": true
        }
    ],
    "matchingInfo": {
        "status": "timeout"
    },
    "requestingStatus": "requested",
    "requestingInfo": {
        "requestTimeUtc": "2024-12-20T06:37:47.99"
    }
}

Group Information Retrieval (by Code)¶

This is an API that checks whether the group exists using the code (groupCode) provided by the group leader (room leader).

요청 URL¶

Header parameters¶

Path parameters¶

Query parameters¶

Response¶

Request sample¶

curl --location 'http://sandbox-api-match.withhive.com/gameindexes/2/groups?code=0343322' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a'

Response sample¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1
}

Member Information Update¶

This is the API used when a member belonging to a group wants to change their information. The information that can be changed is as follows.

• Ready status (ready) - The group leader (room leader) is an unused item.\n
• Score (point)\n
• Additional information (extraData)

Request URL¶

Header parameters¶

Path parameters¶

Request body¶

Response¶

Request sample¶

curl --location --request PATCH 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/players/2/group/memberinfo' --header 'Content-Type: application/json' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a' --data '{"ready":false,"point":0,"extraData":""}'

Response sample¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1
        }
    ],
    "requestingStatus": "notRequested"
}

Matching request¶

This is the API requested for each group to start matching.

• You must create the match corresponding to matchId in advance in the console. (Same as personal matching request)
• There must be at least 2 members at the time of the request.
• Members who are not the group leader (room leader) must have their 'ready status' (Ready) set to true.
• If there is an existing match in progress, it must be organized (deleted) before making a request.
• Only the group representative (room leader) can make the request.

Request URL¶

Header parameters¶

Path parameters¶

Request body¶

Response¶

Request sample¶

curl --location 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/group/request' --header 'Content-Type: application/json' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a' --data '{"playerId":1}'

Response sample¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1
        },
        {
            "playerId": 2,
            "ready": true
        }
    ],
    "matchingInfo": {
        "status": "matchingInProgress"
    },
    "requestingStatus": "requested",
    "requestingInfo": {
        "requestTimeUtc": "2024-12-05T07:35:35.15"
    }
}

Cancel matching request¶

Request URL¶

Header parameters¶

Path parameters¶

Request body¶

Response¶

Request sample¶

curl --location --request DELETE 'https://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/group/request' --header 'Content-Type: application/json' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a' --data '{"playerId":3}'

Response sample¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1
        },
        {
            "playerId": 2
        }
    ],
    "requestingStatus": "notRequested"
}

Public response¶

This is a description of the fields commonly used in the API responses related to groups.

memberInfos¶

The fields consisting of information about members belonging to the group (including the group leader or room leader) are as follows.

matchInfo¶

The fields consisting of gameIndex and matchId information to which the group belongs are as follows.

requestingStatus¶

The values corresponding to the matching request status field are as follows.

• notRequested: Matching not requested
• requested: Matching requested

requestingInfo¶

This is the matching request information field.

matchingInfo¶

The fields consisting of matching progress information are as follows.

matchingInfo → status¶

The values corresponding to the status field in the matching progress information are as follows.

• matchingInProgress : Matching in progress
• timeout : No match was made within the time limit
• matched : Match successful

matchingInfo → privateInfos¶

The fields that make up the personal matching app user information among the matching progress information are as follows. It is in the same data format as matchingInfo → teamInfos → playerInfos.

matchingInfo → teamInfos¶

The fields that make up the team information matched in the group matching of the matching progress information are as follows.

matchingInfo → teamInfos → playerInfos¶

The fields that configure the app user information of the teams matched in the matching progress are as follows.
It is in the same data format as matchingInfo → privateInfos.