<commit_before>.. TODO kegan
  Room config (specifically: message history,
  public rooms). /register seems super simplistic compared to /login, maybe it
  would be better if /register used the same technique as /login? /register should
  be "user" not "user_id".


How to use the client-server API
================================

This guide focuses on how the client-server APIs *provided by the reference 
home server* can be used. Since this is specific to a home server 
implementation, there may be variations in relation to registering/logging in
which are not covered in extensive detail in this guide.

If you haven't already, get a home server up and running on 
``http://localhost:8008``.


Accounts
========
Before you can send and receive messages, you must **register** for an account. 
If you already have an account, you must **login** into it.

`Try out the fiddle`__

.. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/synapse/tree/master/jsfiddles/register_login

Registration
------------
The aim of registration is to get a user ID and access token which you will need
when accessing other APIs::

    curl -XPOST -d '{"user":"example", "password":"<PASSWORD>", "type":"m.login.password"}' "http://localhost:8008/_matrix/client/api/v1/register"

    {
        "access_token": "<KEY>", 
        "home_server": "localhost", 
        "user_id": "@example:localhost"
    }

NB: If a ``user_id`` is not specified, one will be randomly generated for you. 
If you do not specify a ``password``, you will be unable to login to the account
if you forget the ``access_token``.

Implementation note: The matrix specification does not enforce how users 
register with a server. It just specifies the URL path and absolute minimum 
keys. The reference home server uses a username/password to authenticate user,
but other home servers may use different methods.
<commit_msg>Clarify how-to some more.<commit_after>.. TODO kegan
  Room config (specifically: message history,
  public rooms). /register seems super simplistic compared to /login, maybe it
  would be better if /register used the same technique as /login? /register should
  be "user" not "user_id".


How to use the client-server API
================================

This guide focuses on how the client-server APIs *provided by the reference 
home server* can be used. Since this is specific to a home server 
implementation, there may be variations in relation to registering/logging in
which are not covered in extensive detail in this guide.

If you haven't already, get a home server up and running on 
``http://localhost:8008``.


Accounts
========
Before you can send and receive messages, you must **register** for an account. 
If you already have an account, you must **login** into it.

`Try out the fiddle`__

.. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/synapse/tree/master/jsfiddles/register_login

Registration
------------
The aim of registration is to get a user ID and access token which you will need
when accessing other APIs::

    curl -XPOST -d '{"user":"example", "password":"<PASSWORD>", "type":"m.login.password"}' "http://localhost:8008/_matrix/client/api/v1/register"

    {
        "access_token": "<KEY>", 
        "home_server": "localhost", 
        "user_id": "@example:localhost"
    }

NB: If a ``user`` is not specified, one will be randomly generated for you. 
If you do not specify a ``password``, you will be unable to login to the account
if you forget the ``access_token``.

Implementation note: The matrix specification does not enforce how users 
register with a server. It just specifies the URL path and absolute minimum 
keys. The reference home server uses a username/password to authenticate user,
but other home servers may use different methods. This is why you need to
specify the ``type`` of method.

{'fraction_non_alphanumeric': 0.11267239136091595, 'fraction_numerical': 0.00624512099921936, 'mean_word_length': 3.928205128205128, 'pattern_counts': {'":': 12, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1049027', 'n_tokens_mistral': 1062, 'n_tokens_neox': 1009, 'n_words': 498}