{% extends 'base.html' %}

{% block title %}API - MetaBrainz Foundation{% endblock %}

{% block content %}
  <div id="api">

    <h1 class="page-title">{{ _('MetaBrainz API') }}</h1>

    <em>
    {{ _('All endpoints require an access token which you can get from your
    <a href="%(profile_url)s">profile page</a>.', profile_url=url_for('supporters.profile')) }}
    </em>

    <h2>{{ _('MusicBrainz Live Data Feed') }}</h2>
    <p>{{ _('There are two endpoints for fetching live data:') }}</p>

    <h3>{{ _('Hourly Replication Packets') }}</h3>
    <p>
      <code>
        GET {{ url_for('api_musicbrainz.replication_hourly',
                       _external=True, _scheme=config.PREFERRED_URL_SCHEME,
                       packet_number=42, token="TOKEN")
                  | replace("42", "<PACKET_NUMBER>")
                  | replace("TOKEN", "<ACCESS_TOKEN>")
            }}
      </code>
    </p>
    <p>
      {{ _('It is possible to get a signature for each replication packet. Just replace
      <code>.tar.bz2</code> with <code>.tar.bz2.asc</code>.') }}
    </p>
    <p>
      {{ _('You can find the latest replication packet number from this endpoint:') }}<br />
      <code>
        GET {{ url_for('api_musicbrainz.replication_info',
                       _external=True, _scheme=config.PREFERRED_URL_SCHEME,
                       token="TOKEN")
                  | replace("TOKEN", "<ACCESS_TOKEN>")
            }}
      </code>
    </p>

    <h3>{{ _('Hourly Incremental JSON Dumps') }}</h3>
    <p>
      <code>
        GET {{ url_for('api_musicbrainz.json_dump',
                       _external=True, _scheme=config.PREFERRED_URL_SCHEME,
                       packet_number=42, entity_name="ENTITY_NAME",
                       token="TOKEN")
                  | replace("42", "<PACKET_NUMBER>")
                  | replace("ENTITY_NAME", "<ENTITY_NAME>")
                  | replace("TOKEN", "<ACCESS_TOKEN>")
            }}
      </code>
    </p>
    <p>
      {{ _('The JSON dumps are partitioned by entity type. <code>&lt;ENTITY_NAME&gt;</code> can be one of: area, artist, event, instrument, label, place, recording, release, release-group, series, or work.') }}
    </p>
    <p>
      {{ _('It’s possible that a JSON dump for a particular entity type doesn’t exist if no entities of that type have changed in a given hour.') }}
    </p>
    <p>
      {{ _('Each dump contains a file named <code>mbdump/&lt;ENTITY_NAME&gt;</code>. This file must be read line-by-line; each line contains one changed entity in JSON format.') }}
    </p>
    <p>
      {{ _('As with replication packets, you can obtain a file signature by replacing <code>.tar.xz</code> with <code>.tar.xz.asc</code>.') }}
    </p>
  </div>
{% endblock %}