HTTP API reference
==================

Before diving into the HTTP API make sure you've signed-up and `installed Musketeer`_.

.. _installed Musketeer: /Installation.html

**Introduction**

If you don't want to implement the JavaScript library, or if you want to participate and convert users
on the server-side, you can use the HTTP API directly.

You send data in requests with base64-encoded JSON objects provided in the `data` query parameter.

**Example**

.. code-block:: javascript
	:linenos:

	// The properties for a given request.
	const properties = {
		identity_id: 123,
		project_id: '..',
		host: 'musketeer.ai',
		test: 'MyFirstTest',
		variants: ['A', 'B'],
	};

	// JSON-ify the properties and base64 encode the JSON object.
	const data = new Buffer(JSON.stringify(properties)).toString('base64');

	// Now you can send a GET request to e.g.
	// https://musketeer.ai/api/participants?data=${data}

GET /api/participate
-----------------

**Description**

Participates the user with the client id or identity id to the test. If you specify the ``variant``,
the user joins ``variant``, otherwise, the user joins the target variant. If the
test does not exist it gets created.

===================			============================================================================
Key							Description
===================			============================================================================
[client_id]					The client id of the user. The client id is generated by Musketeer. If you can't provide a client id you must provide the identity_id instead.
[identity_id]				The identity id of the user. You can specify the identity id of the user by invoking Musketeer('identify', userID).
project_id					The id of the project.
host						The host of the domain e.g. ``musketeer.ai``.
test_name					The name of the test to participate.
[variant]					The name of the variant to join. If not specified, the server will decide which variant to join.
variants					The variants as specified in `Musketeer('test')`_. This is either an array of names, or an array of variants with name and weight properties.
===================			============================================================================

GET /api/convert
-----------------

**Description**

Converts the user in the test.

===================			============================================================================
Key							Description
===================			============================================================================
[client_id]					The client id of the user. The client id is generated by Musketeer. If you can't provide a client id you must provide the identity_id instead.
[identity_id]				The identity id of the user. See `Musketeer('identify', userID)`_.
project_id					The id of the project.
host						The host of the domain e.g. ``musketeer.ai``.
test_name					The name of the test to convert.
===================			============================================================================

.. _Musketeer('identify', userID): /JavaScript_API_reference.html#musketeer-identify-userid