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

.. contents:: :depth: 2

The badge API supports the creation, deletion, and updating of badges that could be used to distinguish your content from other content on your site.

.. _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 requirements apply here as for :ref:`creating-badges`, only that there are no required
fields.

Response
********

The response structure here is the same as the response structure used for :ref:`creating-badges`.

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 all badges' information.

.. code::

   GET /api/1.3/badges

Parameters
**********

No parameters are required as all the badges are returned.

Response
********

It returns a list of objects whose structure and contents are detailed here: :ref:`creating-badges`.

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

Fetches a single badge by ID.

.. code::

   GET /api/1.3/badges/<id>

Response
********

The response structure here is the same as the response structure used for :ref:`creating-badges`.