Getting Started

Registration

A Credentials that will provide access to Realm API.
The process of obtaining Credentials should be a one-time activity.

If you don't already have a devId and authKey, click here to become developer.

If your application is accepted, you will receive an e-mail from Hi-Rez Studios containing your personal Credentials within a few days.

---

Credentials

To access the API you'll need your own set of Credentials which consist of a Developer ID (devId) and an Authentication Key (authKey).

Here are the Credentials for a sample account:

DevId	AuthKey
1004	23DF3C7E9BD14D84BF892AD206B6755C

Use your personal Credentials to access the API via a Representational State Transfer (REST) Web Service hosted at http://api.realmroyale.com.

NOTE: The same devId and authKey combination should work for SmiteAPI, PaladinsAPI and RealmAPI, across all supported platforms. Do not request a new, If you already have a Credentials.

---

Sessions

To begin using the API, you will first need to establish a valid Session.

To do so you will start a Session (via the CreateSession method) and receive a session_id. Sessions are used for authentication, security, monitoring, and throttling.

Once you obtain a Session, you will pass it to other methods for authentication. Each session only lasts for 15 minutes and must be recreated afterward.

More details regarding Session creation are provided later in this document.

---

Signature

A MD5 hash of (devID + method + authKey + timestamp)

Actually the authKey isn't passed directly, but instead embedded and hashed in another parameter (signature).

It's a combination of devID, authKey, method (without the response format), and the Timestamp.

string: {devid}{method}{authKey}{timestamp} - converted to MD5 - for example strings will be like: 1004createsession23DF3C7E9BD14D84BF892AD206B6755C20170804143735 -> MD5 -> cbda2611f11b4e229ea1db6838de0ac5

C# Sample:

private static string GetMD5Hash (string input) {
	using (var md5 = System.Security.Cryptography.MD5.Create ()) {
		var bytes = md5.ComputeHash (System.Text.Encoding.UTF8.GetBytes (input));
		var stringBuilder = new System.Text.StringBuilder ();
		foreach (byte b in bytes)
			stringBuilder.Append (b.ToString ("x2").ToLower ());
		return stringBuilder.ToString ();
	}
}
public string generateSignature (int devId, string method, string authKey, string timestamp) {
	return GetMD5Hash (devKey + method + authKey + timestamp);
}
var signature = generateSignature (1004, "createsession", "23DF3C7E9BD14D84BF892AD206B6755C", getTimeStamp ());

Java Sample:

private static String generateSignature (int devId, String authKey, String method, String timestamp) {
  String templateSignature = devId + method + authKey + timestamp;
  StringBuilder signatureBuilder = new StringBuilder ();
  try {
    MessageDigest md = MessageDigest.getInstance ("MD5");
    md.update (templateSignature.getBytes ());
    byte [] bytes = md.digest ();

    for (byte b : bytes) {
      String hex = Integer.toHexString (0xff & b);
      if (hex.length () == 1) {
        signatureBuilder.append ("0");
      }
      signatureBuilder.append (hex);
    }
  } catch (NoSuchAlgorithmException e) {
    e.printStackTrace ();
  }

  return signatureBuilder.toString ();
}

public final String signature = generateSignature (1004, "createsession", "23DF3C7E9BD14D84BF892AD206B6755C", getTimestamp ());

Javascript Sample:

const md5 = require ('md5');
function generateSignature (devId, method, authKey, timestamp) {
	return md5 (`${devId}${method}${apiKey}${timestamp}`);
}
var signature = generateSignature (1004, "createsession", "23DF3C7E9BD14D84BF892AD206B6755C", getTimeStamp ());

Python Sample:

from hashlib import md5 as GetMD5Hash
def __encode__ (_input, encodeType: str = "utf-8"):
	return str (_input).encode (encodeType)
def generateSignature (devId, method, authKey, timestamp):
	return GetMD5Hash (__encode__ (devId) + __encode__ (method) + __encode__ (authKey) + __encode__ (timestamp)).hexdigest ()
signature = generateSignature (1004, "createsession", "23DF3C7E9BD14D84BF892AD206B6755C", getTimeStamp ());

---

Timestamp

The current UTC time (GMT +0) formatted to 'YYYYMMDDHHmmss'.
Will be like 20170804143735 - for 08.04.2017 2:37:35 PM (UTC)

C# Sample:

public static string getTimeStamp (string format = "yyyyMMddHHmmss") {
	return System.DateTime.UtcNow.ToString (format); 
}
var timestamp = getTimeStamp ();

Java Sample:

private static String getTimestamp () {
  SimpleDateFormat sdf = new SimpleDateFormat ("yyyyMMddHHmmss");
  sdf.setTimeZone (new SimpleTimeZone (SimpleTimeZone.UTC_TIME, "UTC"));
  return sdf.format (new Date ());
}

public final String timestamp = getTimestamp ();

Javascript Sample:

const moment = require ('moment');
function getTimeStamp () {
	return moment.utc ().format ('YYYYMMDDHHmmss');
}
var timestamp = getTimeStamp ();

Python Sample:

def getTimeStamp (format = "%Y%m%d%H%M%S"):
	from datetime import datetime
	return datetime.utcnow ().strftime (format)
timeStamp = getTimeStamp ()

---

API Access Limits

To throttle API Developer access various limits have been setup to prevent over use of the API (either intentional, more likely unintentional “over use”).

Here are the default initial limitations for API Developers:

Concurrent Sessions	Daily Sessions	Session Time	Daily Request
50	500	15 minutes	7500

---

Platform Endpoint Base URLs

To retrieve all information from the Realm Royale API, you will need to append all requests to the Realm Royale API endpoint, and all requests must begin with the method you're wanting to access concatenated with the response type you're wanting.

PC	PS4	XBOX
http://api.realmroyale.com/realmapi.svc	No yet	No yet

---

Calling API Methods

BaseURLEndpoint/MethodPattern[ResponseFormat]/Params
The url format for calling a method from the api

Name	Description	Example
BaseURLEndpoint	The Endpoint that you want to use	http://api.realmroyale.com/realmapi.svc
MethodPattern	The pattern for the method above, where [ResponseFormat] is replaced by the formatting that you want returned (either JSON or XML).	/CreateSessionJSON
Params	The method params	/{devID}/{signature}/{timestamp}

URI example: http://api.realmroyale.com/realmapi.svc/CreateSessionJSON/{devID}/{signature}/{timestamp}

---

Ret_msg

Except when using the CreateSession method, the ret_msg will not be null when you catch an error.

Message Error	Description
Approved	When you got a Session
Daily request limit reached
Error while comparing Server and Client timestamp
Exception - Timestamp
Exception - Timestamp Your signature: {signature} Your timestamp: {timestamp} Your session ID: {session_id}
Exception while validating developer access.Invalid signature.	You've submit a wrong devID and/or authKey
Failed to validate DeveloperId
Invalid date format
Invalid session id.	You've an invalid or "died" Session
Invalid signature
Maximum number of active sessions reached	You've 25 Sessions active actually
No Match Details:{match_id}
Unauthorized Developer Id

Or if the ret_msg is containing: dailylimit (7500 requests reached) / 404 ""