{% extends 'main/layout.html' %}

{% block title %}API{% endblock %}

{% block content %}
<main>
    <h1>API</h1>
    <p>
        We provide an API to allow programmatic updating of one’s blog.
    </p>

    <dl>
        <dt>API Key</dt>
        <dd>{{ request.user.api_key|default:"your-api-key" }}</dd>
    </dl>
    {% if request.user.is_authenticated %}
    <p>
        <a href="{% url 'api_reset' %}">Reset API key »</a>
    </p>
    {% endif %}

    <h2>Notes</h2>
    <ul>
        <li>
            One can <a href="{% url 'api_reset' %}">reset their API key</a>.
            This will invalidate their key and issue a new one.
        </li>
        <li>The API is at <code>https://mataroa.blog/api/</code></li>
        <li>All API endpoints end with a trailing slash.</li>
        <li>
            <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type">Content type</a>
            <code>application/json</code> is expected.
        </li>
        <li>There is no rate limiting.</li>
    </ul>

    <hr>

    <h2>Authentication</h2>
    <p>
        We authenticate requests using the
        <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization">Authorization</a>
        HTTP header, using the <code>Bearer</code> scheme.
    </p>
    <pre><code>Authorization: Bearer {{ request.user.api_key|default:"your-api-key" }}</code></pre>

    <h2>POST /api/posts/</h2>
    <p>
        Create new post.
    </p>

    <strong>Parameters</strong>
    <ul>
        <li><code>title</code>: string [required]</li>
        <li><code>body</code>: string [optional]</li>
        <li><code>published_at</code>: string (ISO date eg. 2006-01-31) [optional]</li>
        <li><code>tags</code>: string [optional]</li>
    </ul>

    <strong>Request</strong>
    <pre><code>{
    "title": "New blog",
    "body": "## Why?\n\nEveryone wants a blog, right?",
    "published_at": "2020-09-21"
    "tags": "life, tech, coding",
}</code></pre>

    <strong>Response</strong>
    <pre><code>{
    "ok": true,
    "slug": "new-blog",
    "url": "{{ protocol }}//{{ request.user.username|default:"your-username" }}.{{ host }}/blog/new-blog/"
}</code></pre>

    <strong>curl</strong>
    <pre><code>$ curl -X POST \
    -H 'Authorization: Bearer {{ request.user.api_key|default:"your-api-key" }}' \
    -d '{"title": "New blog", "body": "## Why?\n\nEveryone needs a blog, right?"}' \
    {{ protocol }}//{{ host }}/api/posts/
</code></pre>

    <h2>GET /api/posts/&lt;post-slug&gt;/</h2>
    <p>
        Get single post.
    </p>

    <strong>Parameters</strong>
    <ul>
        <li><em>(no parameters)</em></li>
    </ul>

    <strong>Response</strong>
    <pre><code>{
    "ok": true,
    "slug": "new-blog",
    "title": "New blog",
    "body": "Welcome!"
    "published_at": "2020-09-21"
    "url": "{{ protocol }}//{{ request.user.username|default:"your-username" }}.{{ host }}/blog/new-blog/"
}</code></pre>

    <strong>curl</strong>
    <pre><code>$ curl -X GET \
    -H 'Authorization: Bearer {{ request.user.api_key|default:"your-api-key" }}' \
    {{ protocol }}//{{ host }}/api/posts/new-blog/
</code></pre>

    <h2>PATCH /api/posts/&lt;post-slug&gt;/</h2>
    <p>
        Update existing post.
    </p>

    <strong>Parameters</strong>
    <ul>
        <li><code>title</code>: string [optional]</li>
        <li><code>slug</code>: string (slug; no spaces) [optional]</li>
        <li><code>body</code>: string [optional]</li>
        <li><code>published_at</code>: string (ISO date eg. 2006-01-31; or empty to unpublish) [optional]</li>
    </ul>

    <strong>Request</strong>
    <pre><code>{
    "title": "Updating my new blog",
    "slug": "updating-blog",
    "body": "Welcome back!"
    "published_at": "2020-09-21"
}</code></pre>

    <strong>Response</strong>
    <pre><code>{
    "ok": true,
    "slug": "updating-blog",
    "url": "{{ protocol }}//{{ request.user.username|default:"your-username" }}.{{ host }}/blog/updating-blog/"
}</code></pre>

    <strong>curl</strong>
    <pre><code>$ curl -X PATCH \
    -H 'Authorization: Bearer {{ request.user.api_key|default:"your-api-key" }}' \
    -d '{"title": "Updating my new blog", "body": "Rethinking and rewriting."}' \
    {{ protocol }}//{{ host }}/api/posts/introducing-my-new-blog/
</code></pre>


    <h2>DELETE /api/posts/&lt;post-slug&gt;/</h2>
    <p>
        Delete post.
    </p>

    <strong>Parameters</strong>
    <ul>
        <li><em>(no parameters)</em></li>
    </ul>

    <strong>Response</strong>
    <pre><code>{
    "ok": true
}</code></pre>

    <strong>curl</strong>
    <pre><code>$ curl -X DELETE \
    -H 'Authorization: Bearer {{ request.user.api_key|default:"your-api-key" }}' \
    {{ protocol }}//{{ host }}/api/posts/introducing-my-new-blog/
</code></pre>


    <h2>GET /api/posts/</h2>
    <p>
        List all posts.
    </p>

    <strong>Parameters</strong>
    <ul>
        <li><em>(no parameters)</em></li>
    </ul>

    <strong>Response</strong>
    <pre><code>{
    "ok": true,
    "post_list": [
        {
            "title": "On life",
            "slug": "on-life",
            "body": "What is life?\n\nAn illusion, a shadow, a story.",
            "published_at": null,
            "url": "{{ protocol }}//{{ request.user.username|default:"your-username" }}.mataroa.blog/blog/on-life/"
        },
        {
            "title": "New blog",
            "slug": "new-blog",
            "body": "With health!",
            "published_at": "2020-10-19",
            "url": "{{ protocol }}//{{ request.user.username|default:"your-username" }}.mataroa.blog/blog/new-blog/"
        }
    ]
}</code></pre>

    <strong>curl</strong>
    <pre><code>$ curl -X GET \
    -H 'Authorization: Bearer {{ request.user.api_key|default:"your-api-key" }}' \
    {{ protocol }}//{{ host }}/api/posts/
</code></pre>

    <div style="margin-top: 64px;"></div>
</main>
{% endblock content %}