Using the REST API

Preliminary steps

• Your scene should have a CoreApplication component.
• You must have setup valid Network Parameters.
• You must have setup the SSO Handler.

Calling a Endpoint

Calling an endpoint is done in two simple steps:

• Create the desired endpoint with parameters
• Execute it and give a completion Action

CoreApplication coreApplication = CoreApplication.Instance;

Endpoint endpoint = new Endpoint(coreApplication.OAuthGate, CoreApplication.NetworkParameters);
endpoint.Execute((result, webError) =>
{
        if (webError != null)
        {
                // An error occured!
        }
        else
        {
                // Use result
        }
}

When an error occurs, you receive a WebError in your completion Action. From this object you can retrieve the error code and message. WebError is the parent class of OAuthError and ApiResponseError. You may want to cast the error in one of these children classes to get more details about what went wrong.

If the call succeeded, you receive a templated result object, specific to the endpoint. Some endpoints don’t return any object. In this case, the completion Action is only templated on a WebError

As an example:

• Calling GetUserDetailsEndpoint gives you a User
• Calling GetAchievementByIdEndpoint gives you an Achievement
• Calling AddBuddyEndpoint doesn’t return any object in the completion action
• …

See list of endpoints for a complete map of endpoints in relation their HTTP counterparts.

Paginated Endpoints

Some endpoints return collections of objects (lists) that can be very long. They don’t send back the complete list but a paginated subpart.

These endpoints inherit from EndpointWithPaginatedResponse and require two extra parameters when you create them:

int offset, int limit

• Offset is the rank of the first returned element among all available elements. Most of the time, you want it to be equal to 0 to start with the first element.
• Limit is the max number of element returned per page, with a hard limit set to 100.

The completion Action is also modified: you receive a PaginatedResult allowing you to request more data via Next, Prev, First and Last properties.

The following sample retrieves users by id:

int[] userIds = new int[] {...};
SearchByIdEndpoint endpoint = new SearchByIdEndpoint(coreApplication.OAuthGate, coreApplication.NetworkParameters, userIds, Extras.None, 0, 100);

List<UserSearchResult> results = new List<UserSearchResult>();

Action<PaginatedResult<UserSearchResult>, WebError> searchCompletion = null;
searchCompletion = (PaginatedResult<UserSearchResult> result, WebError webError) =>
{
        if (webError != null)
        {
                // An error occured!
        }
        else
        {
                // store the elements from this page for further use
                results.AddRange(result.Elements);

                if (result.Next == null)
                {
                        // all the elements have been retrieved;
                }
                else
                {
                        result.Next(searchCompletion);
                }
    }
};

endpoint.Execute(searchCompletion);

You can find more information in the API Doc.