Badges API
==========

The badge API supports creating, updating and deleting badges that could be used to reward
your content.

.. _creating-badges:

Creating badges
---------------

Creates a badge.

.. code::

   POST /api/1.3/badges

Parameters
**********

+--------------------+-------------------+--------------------------------------------------+
| Name               | Type              | Description                                      |
+====================+===================+==================================================+
| ``name``           | String            | Name  - Required                                 |
+--------------------+-------------------+--------------------------------------------------+
| ``image_id``       | String            | ID of the uploaded image - Required              |
+--------------------+-------------------+--------------------------------------------------+
| ``tags``           | Array of strings  | Tags - Optional                                  |
+--------------------+-------------------+--------------------------------------------------+
| ``category``       | Integer           || Category - Optional                             |
|                    |                   || Choices:                                        |
|                    |                   |                                                  |
|                    |                   || - ``0``: Normal (Default)                       |
|                    |                   || - ``1``: Sponsored                              |
+--------------------+-------------------+--------------------------------------------------+
| ``description``    | String            | Description - Required for sponsored badges only |
+--------------------+-------------------+--------------------------------------------------+
| ``link``           | Object            | Link - Required for sponsored badges only        |
+--------------------+-------------------+--------------------------------------------------+

Response
********

.. code:: json

   {
	"id": 50,
	"name": "My first badge",
	"image_id": 400,
	"image": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/210x.jpg",
	"tags": ["foo", "bar"],
	"category": 0,
	"description": "",
	"link": "",
	"order": 0,
   }

Editing badges
--------------

Edits a badge.

.. code::

   PUT /api/1.3/badges/<id>

Parameters
**********

The same specification from :ref:`creating-badges` section applies here but there is no required
fields.

Response
********

The same specification from :ref:`creating-badges` section applies here.

Deleting badges
---------------

Deletes a badge.

.. code::

   DELETE /api/1.3/badges/<id>

Response
********

The response payload is an empty object.

.. code:: json

   {}

List badges
-------------

Fetches badges information.

.. code::

   GET /api/1.3/badges

Parameters
**********

No parameters, all badges are returned.

Response
********

It returns a list of objects described at :ref:`creating-badges` section.

Get a single badge
------------------

Fetch a single badge by ID.

.. code::

   GET /api/1.3/badges/<id>

Response
********

The same specification from :ref:`creating-badges` section applies here.