Using the REST API
==================

Preliminary steps
------------------

- Your scene should have a `CoreApplication <coreapplication.html>`_ component.
- You must have setup valid `Network Parameters <networkparameters.html>`_.
- You must have setup the `SSO Handler <SSO.html>`_.

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

.. code:: csharp

	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 <endpoints.html>`_ 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:

.. code:: csharp

	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:

.. code:: csharp

	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 <http://apidoc.asmodee.net/#api-intro-collection-pagination>`_.