Create Leaderboard Leaderboard REST Endpoint

Ben Tiedt — Tue, 19 Nov 2019 20:23:57 GMT

Current Revision posted to API Documentation by Ben Tiedt on 11/19/2019 20:23:57

URLs

POST api.ashx/v2/leaderboards.xml (or .json)

Request Parameters

Name	Type	Description	Location	Required
Name	`string`	Name of the Leaderboard	Request Body	Required
NumberOfLeaders	`int`	Number of Users to show on the Leaderboard	Request Body	Required
Description	`string`	Description of the Leaderboard	Request Body	Optional
ApplicationKey	`string`	Application Key for url	Request Body	Optional
ContainerId	`Guid?`	Filter points to those earned within a certain Container. Optional.	Request Body	Optional
StartDate	`DateTime`	Specify the earliest date scores will count for this leaderboard. Either StartDate + EndDate, or TimeSpanValue + TimeSpanType are required.	Request Body	Optional
EndDate	`DateTime`	Specify the earliest date scores will count for this leaderboard. Either StartDate + EndDate, or TimeSpanValue + TimeSpanType are required.	Request Body	Optional
StartDisplayDate	`DateTime`	Only show the leaderboard on the site after this date. Optional, defaults to StartDate.	Request Body	Optional
EndDisplayDate	`DateTime`	Only show the leaderboard on the site before this date. Optional, defaults to EndDate	Request Body	Optional
TimeSpanValue	`int`	Specify the number of (days/months/years), based on the TimeSpanType. Either StartDate + EndDate, or TimeSpanValue + TimeSpanType are required.	Request Body	Optional
TimeSpanType	`string`	Specify the time of time span for calculations (days/months/years). Either StartDate + EndDate, or TimeSpanValue + TimeSpanType are required. Options are: Day, Month, Year.	Request Body	Optional
PeriodType	`string`	Specify the anchor for the time span rolling window. Past (default) = generalized timespan counting backwards from current time or EndDate. Current = timespan starting from the beginning of the specified month/day/year. Options are: AllTime, Static, Rolling.	Request Body	Optional
IncludeRolesFilter	`string`	Comma separated list of Site RoleIds. Used to limit the leaders for the leaderboard. Only users assigned the provided site roles will be eligable to be on the leaderboard.	Request Body	Optional
ExcludeRolesFilter	`string`	Comma separated list of Site RoleIds. Used to limit the leaders for the leaderboard. Only users who are not assigned the provided site roles will be eligable to be on the leaderboard.	Request Body	Optional

Example Requests

C# REST SDK

This example uses the REST SDK to access the Community REST API within a .Net C# application. In the example, USER_NAME is the user name of the effective user for the request and OAUTH_CLIENT_ID and OAUTH_SECRET are the OAuth client ID and secret, respectively, associated to this application as configured in Administration > Integration > OAuth Clients with the "Client Credentials" grant type enabled. See the documentation for the REST SDK for more details about installation, configuration, and usage options.

var host = new ClientCredentialsRestHost("USER_NAME", "https://mysite.com/", "OAUTH_CLIENT_ID", "OAUTH_SECRET");
var response = host.PostToDynamic(2, "leaderboards.json", false, new RestPostOptions {
	PostParameters = new System.Collections.Specialized.NameValueCollection {
		{ "Name", "name" },
		{ "NumberOfLeaders", "6" }
	}
});

Widget Javascript

This example uses the [[rest JavaScript API Module|rest JavaScript API]] to access the Community REST API within the Community web UI. When accessing the REST API through the javascript API, the effective user is the current contextual user of the web interface.

jQuery.telligent.evolution.post({
	url: jQuery.telligent.evolution.site.getBaseUrl() + 'api.ashx/v2/leaderboards.json',
	data: { 
		'Name': 'name',
		'NumberOfLeaders': '6'
	},
	success: function(response) {

	}
});

cURL

This example uses the cURL command-line HTTP utility. ENCODED_TOKEN in the example is the base64-encoded concatenation of the user's API key (created from the user's profile), a colon (:), and the user's user name. Learn more about using the REST API.

curl -H "Rest-User-Token: ENCODED_TOKEN" -d "Name=name&NumberOfLeaders=6" -X POST https://mysite.com/api.ashx/v2/leaderboards.xml

Example Responses

XML

<?xml version="1.0" encoding="utf-16"?>
<Response>
  <Leaderboard>
    <Id>61</Id>
    <Name>name</Name>
    <Description>description</Description>
    <ContentId>49fec544-6df7-4a82-872b-f8be586d5e9e</ContentId>
    <ContentTypeId>9f5a6721-639d-4e1d-ab6a-ce63b7750f46</ContentTypeId>
    <CreatedDate>2012-01-04T00:00:00</CreatedDate>
    <IsEnabled>true</IsEnabled>
    <NumberOfLeaders>6</NumberOfLeaders>
    <ContainerId>fe65240b-044c-4292-9946-f10e0361ecff</ContainerId>
    <StartDate>2012-05-02T00:00:00</StartDate>
    <EndDate>2012-06-04T00:00:00</EndDate>
    <StartDisplayDate>2011-05-28T00:00:00</StartDisplayDate>
    <EndDisplayDate>2011-12-09T00:00:00</EndDisplayDate>
    <LastCalculatedDate>2012-03-29T00:00:00</LastCalculatedDate>
    <TimeSpanLength>25</TimeSpanLength>
    <TimeSpanType>timespantype</TimeSpanType>
    <TimeSpanFilterType>timespanfiltertype</TimeSpanFilterType>
    <IncludeRolesFilter>
      <Role>
        <Id>8</Id>
        <Name>name</Name>
        <Description>description</Description>
        <GroupId>4</GroupId>
        <IsSystemRole>true</IsSystemRole>
        <AvatarUrl>avatarurl</AvatarUrl>
        <PermissionEntries>
          <PermissionEntry>
            <Id>2d525bad-c4df-470d-a193-a1c6d66e5c3e</Id>
            <PermissionId>permissionid</PermissionId>
            <Name>name</Name>
            <IsAllowed>true</IsAllowed>
            <IsImmediate>true</IsImmediate>
          </PermissionEntry>
          <PermissionEntry>
            <Id>bd519379-b61f-4e2f-b0f9-c0f28c5cceb1</Id>
            <PermissionId>permissionid</PermissionId>
            <Name>name</Name>
            <IsAllowed>true</IsAllowed>
            <IsImmediate>true</IsImmediate>
          </PermissionEntry>
        </PermissionEntries>
      </Role>
      <Role>
        <Id>7</Id>
        <Name>name</Name>
        <Description>description</Description>
        <GroupId>27</GroupId>
        <IsSystemRole>true</IsSystemRole>
        <AvatarUrl>avatarurl</AvatarUrl>
        <PermissionEntries>
          <PermissionEntry>
            <Id>9ba1ec43-dc34-4e27-a579-4a0855144e2f</Id>
            <PermissionId>permissionid</PermissionId>
            <Name>name</Name>
            <IsAllowed>true</IsAllowed>
            <IsImmediate>true</IsImmediate>
          </PermissionEntry>
          <PermissionEntry>
            <Id>e3715662-2528-4ba1-84a7-bfcd9d548f80</Id>
            <PermissionId>permissionid</PermissionId>
            <Name>name</Name>
            <IsAllowed>true</IsAllowed>
            <IsImmediate>true</IsImmediate>
          </PermissionEntry>
        </PermissionEntries>
      </Role>
    </IncludeRolesFilter>
    <ExcludeRolesFilter>
      <Role>
        <Id>32</Id>
        <Name>name</Name>
        <Description>description</Description>
        <GroupId>52</GroupId>
        <IsSystemRole>true</IsSystemRole>
        <AvatarUrl>avatarurl</AvatarUrl>
        <PermissionEntries>
          <PermissionEntry>
            <Id>6cdcf200-3bad-476d-af45-97b52545c337</Id>
            <PermissionId>permissionid</PermissionId>
            <Name>name</Name>
            <IsAllowed>true</IsAllowed>
            <IsImmediate>true</IsImmediate>
          </PermissionEntry>
          <PermissionEntry>
            <Id>b04540ec-eb38-4fa1-b7bb-e3fde05401b4</Id>
            <PermissionId>permissionid</PermissionId>
            <Name>name</Name>
            <IsAllowed>true</IsAllowed>
            <IsImmediate>true</IsImmediate>
          </PermissionEntry>
        </PermissionEntries>
      </Role>
      <Role>
        <Id>19</Id>
        <Name>name</Name>
        <Description>description</Description>
        <GroupId>112</GroupId>
        <IsSystemRole>true</IsSystemRole>
        <AvatarUrl>avatarurl</AvatarUrl>
        <PermissionEntries>
          <PermissionEntry>
            <Id>44df201a-07e6-42eb-96c7-8ce7ce35aab6</Id>
            <PermissionId>permissionid</PermissionId>
            <Name>name</Name>
            <IsAllowed>true</IsAllowed>
            <IsImmediate>true</IsImmediate>
          </PermissionEntry>
          <PermissionEntry>
            <Id>49fec544-6df7-4a82-872b-f8be586d5e9e</Id>
            <PermissionId>permissionid</PermissionId>
            <Name>name</Name>
            <IsAllowed>true</IsAllowed>
            <IsImmediate>true</IsImmediate>
          </PermissionEntry>
        </PermissionEntries>
      </Role>
    </ExcludeRolesFilter>
    <Application>
      <ApplicationId>9f5a6721-639d-4e1d-ab6a-ce63b7750f46</ApplicationId>
      <ApplicationTypeId>fe65240b-044c-4292-9946-f10e0361ecff</ApplicationTypeId>
      <HtmlName>htmlname</HtmlName>
      <HtmlDescription>htmldescription</HtmlDescription>
      <Url>url</Url>
      <AvatarUrl>avatarurl</AvatarUrl>
      <Container>
        <ContainerId>2d525bad-c4df-470d-a193-a1c6d66e5c3e</ContainerId>
        <ContainerTypeId>bd519379-b61f-4e2f-b0f9-c0f28c5cceb1</ContainerTypeId>
        <HtmlName>htmlname</HtmlName>
        <Url>url</Url>
        <AvatarUrl>avatarurl</AvatarUrl>
      </Container>
    </Application>
  </Leaderboard>
  <Errors>
    <Message>string</Message>
    <Message>string</Message>
  </Errors>
</Response>

JSON

{
  "Leaderboard": {
    "Name": "name",
    "Description": "description",
    "ContentId": "49fec544-6df7-4a82-872b-f8be586d5e9e",
    "ContentTypeId": "9f5a6721-639d-4e1d-ab6a-ce63b7750f46",
    "CreatedDate": "2012-01-04T00:00:00",
    "IsEnabled": true,
    "NumberOfLeaders": 6,
    "ContainerId": "fe65240b-044c-4292-9946-f10e0361ecff",
    "StartDate": "2012-05-02T00:00:00",
    "EndDate": "2012-06-04T00:00:00",
    "StartDisplayDate": "2011-05-28T00:00:00",
    "EndDisplayDate": "2011-12-09T00:00:00",
    "LastCalculatedDate": "2012-03-29T00:00:00",
    "TimeSpanLength": 25,
    "TimeSpanType": "timespantype",
    "TimeSpanFilterType": "timespanfiltertype",
    "IncludeRolesFilter": [
      {
        "Id": 8,
        "Name": "name",
        "Description": "description",
        "GroupId": 4,
        "IsSystemRole": true,
        "ImageUrl": "",
        "AvatarUrl": "avatarurl",
        "PermissionEntries": [
          {
            "Id": "2d525bad-c4df-470d-a193-a1c6d66e5c3e",
            "PermissionId": "permissionid",
            "Name": "name",
            "IsAllowed": true,
            "IsImmediate": true
          },
          {
            "Id": "bd519379-b61f-4e2f-b0f9-c0f28c5cceb1",
            "PermissionId": "permissionid",
            "Name": "name",
            "IsAllowed": true,
            "IsImmediate": true
          }
        ]
      },
      {
        "Id": 7,
        "Name": "name",
        "Description": "description",
        "GroupId": 27,
        "IsSystemRole": true,
        "ImageUrl": "",
        "AvatarUrl": "avatarurl",
        "PermissionEntries": [
          {
            "Id": "9ba1ec43-dc34-4e27-a579-4a0855144e2f",
            "PermissionId": "permissionid",
            "Name": "name",
            "IsAllowed": true,
            "IsImmediate": true
          },
          {
            "Id": "e3715662-2528-4ba1-84a7-bfcd9d548f80",
            "PermissionId": "permissionid",
            "Name": "name",
            "IsAllowed": true,
            "IsImmediate": true
          }
        ]
      }
    ],
    "ExcludeRolesFilter": [
      {
        "Id": 32,
        "Name": "name",
        "Description": "description",
        "GroupId": 52,
        "IsSystemRole": true,
        "ImageUrl": "",
        "AvatarUrl": "avatarurl",
        "PermissionEntries": [
          {
            "Id": "6cdcf200-3bad-476d-af45-97b52545c337",
            "PermissionId": "permissionid",
            "Name": "name",
            "IsAllowed": true,
            "IsImmediate": true
          },
          {
            "Id": "b04540ec-eb38-4fa1-b7bb-e3fde05401b4",
            "PermissionId": "permissionid",
            "Name": "name",
            "IsAllowed": true,
            "IsImmediate": true
          }
        ]
      },
      {
        "Id": 19,
        "Name": "name",
        "Description": "description",
        "GroupId": 112,
        "IsSystemRole": true,
        "ImageUrl": "",
        "AvatarUrl": "avatarurl",
        "PermissionEntries": [
          {
            "Id": "44df201a-07e6-42eb-96c7-8ce7ce35aab6",
            "PermissionId": "permissionid",
            "Name": "name",
            "IsAllowed": true,
            "IsImmediate": true
          },
          {
            "Id": "49fec544-6df7-4a82-872b-f8be586d5e9e",
            "PermissionId": "permissionid",
            "Name": "name",
            "IsAllowed": true,
            "IsImmediate": true
          }
        ]
      }
    ],
    "Application": {
      "ApplicationId": "9f5a6721-639d-4e1d-ab6a-ce63b7750f46",
      "ApplicationTypeId": "fe65240b-044c-4292-9946-f10e0361ecff",
      "HtmlName": "htmlname",
      "HtmlDescription": "htmldescription",
      "Url": "url",
      "AvatarUrl": "avatarurl",
      "Container": {
        "ContainerId": "2d525bad-c4df-470d-a193-a1c6d66e5c3e",
        "ContainerTypeId": "bd519379-b61f-4e2f-b0f9-c0f28c5cceb1",
        "HtmlName": "htmlname",
        "Url": "url",
        "AvatarUrl": "avatarurl"
      }
    },
    "Id": 61
  },
  "Errors": [
    "string",
    "string"
  ]
}