.. index:: HAL and our deviations

.. _hal-and-our-deviations:

HAL and our deviations
======================

For more information see `HAL homepage <http://stateless.co/hal_specification.html>`_ and `HAL RFC draft <http://tools.ietf.org/html/draft-kelly-json-hal-06>`_.

Content-type
------------

The proper content type for HAL documents is ``application/hal+json``. However, to not confuse browsers, our APIs MUST serve the document with content type ``application/json``.

JSON
----

HAL allows any valid `JSON <http://tools.ietf.org/html/rfc7159>`_. We apply the following restrictions:

* `UTF-8 <http://en.wikipedia.org/wiki/UTF-8>`_ character encoding is REQUIRED.
* To ensure interoperability member names MUST be unique in each JSON object, `see the rfc <http://tools.ietf.org/html/rfc7159#section-4>`_.

Field names
-----------

HAL allows any field name to start with the underscore ``_`` character. We reserve the use of the underscore ``_``
character for standardized field. This means that any field which name starts with an underscore is defined in the
HAL specification, or in these guidelines.