Private Match API

This is the API used when applying individual matching during gameplay. To apply group matching play, please use the Group API.

Matching request¶

This is called when starting a match request. The match corresponding to matchId must be pre-created in the Hive console.

Request URL¶

LIVE URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players
SANDBOX URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players
HTTP METHOD	POST
CONTENT-TYPE	application/json

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token for API calls (Bearer)	string	Y

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Project identifier that can be found in the Hive console app center	int	Y
matchId	Identifier for each match created in the Hive console	int	Y

Request body¶

Field Name	Description	Type	Required
playerId	Account identifier	long	Y
point	This is the score to be used for matching. The input range is `0 ~ 999,999,999`. If not entered, it will be processed as `0`.	integer	N
extraData	Additional account information (nickname, level, country, etc.). Up to 256 characters can be entered. It will be included in the matching results.	string	N

Response¶

Field Name	Description
playerId	Account identifier
matchInfo	Information requested `gameIndex`: Value of `gameIndex` `matchId`: Value of `matchId`
requestingStatus	Request status information `requested`: Match request was made successfully `notRequested`: No match request was made, or the match is already completed and there is no ongoing match
requestingInfo	Request information `requestTimeUtc`: Request time based on UTC+0 `point`: `point` entered at the time of request `extraData`: `extraData` entered at the time of request
matchingInfo	Matching progress information (`status`) `matchingInProgress`: Matching is in progress `timeout`: Matching did not occur within the time limit `matched`: Matching completed

Request sample¶

curl --location 'https://sandbox-api-match.withhive.com/gameindexes/1/matchmakings/1/request' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a' \
--data '{
   "playerId":100,
   "point": 1000
}'

Response sample¶

{
   "playerId": 100,
   "matchInfo": {
       "gameIndex": 1,
       "matchId": 1
   },
   "requestingStatus": "requested",
   "requestingInfo": {
       "requestTimeUtc": "2024-06-05T05:09:28.72",
       "point": 1000
   },
   "matchingInfo": {
       "status": "matchingInProgress"
   }
}

Check match status¶

Checking the requested matching status.

요청 URL¶

LIVE URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players
SANDBOX URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players
HTTP METHOD	GET

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token for API calls (Bearer)	string	Y

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Project identifier that can be checked in the Hive console app center	int	Y
matchId	Identifier for each match created in the Hive console	int	Y

Query parameters¶

Field Name	Description	Type	Required
id	User ID (`playerId`)	long	Y

Response¶

Field Name	Description
playerId	Account Identifier
matchInfo	Information requested `gameIndex`: Value of `gameIndex` `matchId`: Value of `matchId`
requestingStatus	Request status information `requested`: Match request was made successfully `notRequested` : No match request was made, or the match is already completed and there is no ongoing match
requestingInfo	Request information `requestTimeUtc`: Request time based on UTC+0 `point`: `point` entered during the request `extraData`: `extraData` entered during the request
matchingInfo	Matching progress information (`status`) `matchingInProgress`: Matching is in progress `timeout`: Matching was not achieved within the time limit `matched`: Matching completed

Request sample¶

curl --location --request GET 'https://sandbox-api-match.withhive.com/gameindexes/1/matchmakings/1/players?id=100' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a'

Response sample¶

When the developer has not yet made a matching request, the matching status result is as follows.

{
   "playerId": 100,
   "matchInfo": {
       "gameIndex": 1,
       "matchId": 1
   },
   "requestingStatus": "notRequested"
}

When a matching request is made 매칭 요청 and the matching is still in progress, it returns the results requested and matchingInProgress.

{
   "playerId": 100,
   "matchInfo": {
       "gameIndex": 1,
       "matchId": 1
   },
   "requestingStatus": "requested",
   "requestingInfo": {
       "requestTimeUtc": "2024-06-05T05:09:28.72",
       "point": 1000
   },
   "matchingInfo": {
       "status": "matchingInProgress"
   }
}

When checking the request status after matching is complete, it returns a result of matched or timeout. This is the state after matching is complete but before receiving the match result callback.

    {
       "playerId": 100,
       "matchInfo": {
           "gameIndex": 1,
           "matchId": 1
       },
       "requestingStatus": "requested",
       "requestingInfo": {
           "requestTimeUtc": "2024-06-05T05:09:28.72",
           "point": 1000
       },
       "matchingInfo": {
           "status": "matched"
       }
   }

When the matching is complete, the Hive server will send the matching result as a callback to the developer's server. After the developer's server receives the matching result callback and returns HTTP Status 200 in response to the Hive server, if the matching request status is checked again, it will change to notRequested as shown below, and the matchingInfo key will be deleted. This is because when the Hive server receives HTTP Status 200 as a callback response, it determines that the matching requested by the developer has been completed and deletes the corresponding matching request transaction.

{
   "playerId": 100,
   "matchInfo": {
       "gameIndex": 1,
       "matchId": 1
   },
   "requestingStatus": "notRequested"
}

	Before matching request	After matching request	After matching result generation	After callback reception
requestingStatus	notRequested	requested	requested	notRequested
matchingInfo > Status	N/A	matchingInProgress	matched or timeout	N/A
Remarks		At the point of matching in progress	At the point before callback reception

Cancel match request¶

Cancelling the matching request. If you cancel the matching request, the matching request transaction in the Hive server will be deleted.

If the matching request is completed after requesting a match and an HTTP Status 200 is sent in response to the match result callback, the Hive server will consider the matching completed internally and delete the corresponding matching request transaction. In this state, even if a cancellation of the matching request is called, the matching request transaction has already been deleted, so the cancellation request will not be executed, and no exceptions will be returned separately.

Request URL¶

LIVE URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}
SANDBOX URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}
HTTP METHOD	DELETE

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token for API calls (Bearer)	string	Y

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Project identifier that can be checked in the Hive console app center	int	Y
matchId	Identifier for each match created in the Hive console	int	Y
playerId	User ID	long	Y

Response¶

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

Request sample¶

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

Response sample¶

There is no special response content upon successful processing.