Matchmaking API

Pre-requisites¶

To use the matchmaking API, you need to prepare the following items.

• Authentication token for API calls (Certification Key): Hive Console App Center > Manage Project > Select your game from the game list > Game Details > Basic Information > Certification Key
• Game index (gameIndex): Hive Console App Center > Manage Project > Select your game from the game list > Game Details > Basic Information > Game Index
• Match ID (matchId): You can check this when creating a match in the Hive Console.

Request URL root¶

Common response codes¶

These are the common API response codes.

Request match¶

Call this API when each user requests a match. The match corresponding to matchId must be pre-created in the Hive Console.

Request URL¶

Header parameters¶

Path parameters¶

Request body¶

Response¶

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¶

Check the status of the requested match.

Request URL¶

Header parameters¶

Path parameters¶

Query parameters¶

Response¶

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¶

The match status when you have not yet made a match request is as follows.

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

Request Match returns requested and matchingInProgress statuses when the match is still in progress.

{
   "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 the match is completed, it returns matched or timeout results. This is the state where the match is completed but the match result callback has not yet been received.

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

Once the match is completed, the Hive Server sends the match result callback to your server. If your server receives the match result callback, returns HTTPStatus 200 to the Hive Server, and if you check the match request status again, it will change to notRequested and the matchingInfo key will be deleted as shown below. This is because the Hive Server considers your match request is completed upon receiving HTTPStatus 200 in response to the callback and deletes the match request transaction.

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

Cancel match request¶

Cancel the match request. When you cancel the match request, the match request transaction will be deleted from the Hive Server.

If the match is completed after Request Match and you have received the Match Result Callback and responded with HTTPStatus 200, the Hive Server will consider the match completed and delete the match request transaction. In this state, even if you call to cancel the match request, as the match request transaction has already been deleted, the cancellation operation will not be executed and no exception will be returned.

Request URL¶

Header parameters¶

Path parameters¶

Response¶

If it is 200 OK, the body 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 specific response if the request is canceled normally.

Match result callback¶

When a match is completed, the Hive Server sends the match result to the your server as a callback. If your server received the match result callback without any issue, your server should respond with HttpStatus 200. By registering the desired server URL in the Hive Console, the match result will be sent to this address as a callback. The address must be a publicly accessible URL. The API information is as follows.

Callback reception URL (Hive Server → Your server)¶

When your server API endpoint is registered in the Hive Console, the Hive Server sends the callback result to this endpoint when the match is completed.

Header parameters¶

Values passed with the callback¶

Callback example (Hive Server → Your server)¶

curl --location 'The API endpoint of your server registered in the Hive Console.' --header 'Content-Type: application/json' --header 'X-Match-Signature: nj2YlgGTlLXcAhrl6ijSgfD71gTWokBiM8WPn72xxg8=' --data '{
   "gameIndex": 1,
   "matchId": 1,
   "matchingInfos": [
       {
           "matchingId": "1:1_2024-06-05T05:43:28.91_1",
           "privateInfos": [
               {
                   "playerId": 100,
                   "point": 1000
               },
               {
                   "playerId": 101,
                   "point": 1000
               }
           ]
       }
   ],
   "timeoutPlayerInfos": []
}'

You can verify the authenticity of the callback result using the value of the Header Parameter X-Match-Signature, and the key to be used for the algorithm calculation can be found in the Hive Console. Below is an example of Java code to obtain the Signature.

import java.nio.charset.StandardCharsets;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public class MatchSignature {  
   private static final String HMAC_SHA_256 = "HmacSHA256";
   private static final String UTF_8 = "UTF-8";
   public String getSignature(String secret, String httpRequestBody) throws Exception {
       SecretKeySpec key = new SecretKeySpec(secret.getBytes(), HMAC_SHA_256);
       Mac mac = Mac.getInstance(HMAC_SHA_256);
       mac.init(key);
       byte[] source = httpRequestBody.getBytes(UTF_8);

       return new String(Base64.getEncoder().encode(mac.doFinal(source)), StandardCharsets.UTF_8);
   }
}

If the callback sent from the Hive Server is successfully received, you should return an HTTP status 200 as a response.

• Response with HttpStatus 200: It is considered that the match has been successfully completed, so the match request will be canceled.
• Response with a value other than HttpStatus 200 or Timeout: The match result callback will be resent at regular intervals.

If the Hive Server can't receive HTTP status 200 response continuously, the match result call back will not be delivered for a certain period for system management purposes.