{% extends "name/base.html" %}
{% load name_extras %}
{% block title %}About{% endblock %}

{% block content %}

    <div class="row">
        <div class="col-sm-12">
            {% include "name/introduction.html" %}

            <h3>Two search modes are available.</h3>
            <p>Notice there are two modes of searching. The first mode is a traditional search which takes a query and a type, filtering records containing your query in either the authorized name field or the variant field. The second search method is more of an existence lookup of the authorized name. The user should request <code>{% absolute_url "name:label" "name_string_here" %}</code>. The API will then either return a 302 Found and redirect to the matching record, or a 404 Not Found.  This page will first address the 'traditional' search API, then the label API.</p>

            <h3>Search API</h3>
            <p>Let's dive right in! The following are various search examples using <a target="_blank" href="http://curl.haxx.se/docs/">curl</a>:</p>

                <!--BEGIN CODE MARKUP-->
            <div>
                <pre>
    $ curl "{% absolute_url "name:search-json" %}?q=joey+liechty"
    [
        {
            "URL": "{% absolute_url "name:detail" "nm0051457" %}",
            "id": "nm0051457",
            "name": "joey liechty",
            "type": "Personal"
        }
    ]

    $ curl "{% absolute_url "name:search-json" %}?q=abc&amp;q_type=Organization&amp;callback=foo"
    foo([
        {
            "URL": "{% url "name:detail" "nm0000063" %}",
            "id": "nm0000063",
            "name": "ABC Shop",
            "type": "Organization"
        }
    ])

    $ curl "{% absolute_url "name:search-json" %}?q_type=Software"
    [
        {
            "URL": "{% absolute_url "name:detail" "nm0051455" %}",
            "id": "nm0051455",
            "name": "Watson",
            "type": "Software"
        },
        {
            "URL": "{% absolute_url "name:detail" "nm0012345" %}",
            "id": "nm0012345",
            "name": "Software Foo",
            "type": "Software"
        },
        {
            "URL": "{% absolute_url "name:detail" "nm0043212" %}",
            "id": "nm0043212",
            "name": "123 SoftCom",
            "type": "Software"
        }
    ]

    $ curl "{% absolute_url "name:search-json" %}?q_type=Software,Organization"
    [
        {
            "URL": "{% absolute_url "name:detail" "nm0051455" %}",
            "id": "nm0051455",
            "name": "Watson",
            "type": "Software"
        },
        {
            "URL": "{% absolute_url "name:detail" "nm0012345" %}",
            "id": "nm0012345",
            "name": "Software Foo",
            "type": "Software"
        },
        {
            "URL": "{% absolute_url "name:detail" "nm0043212" %}",
            "id": "nm0043212",
            "name": "123 SoftCom",
            "type": "Software"
        },
        {
            "URL": "{% absolute_url "name:detail" "nm0000063" %}",
            "id": "nm0000063",
            "name": "ABC Shop",
            "type": "Organization"
        }
    ]
                </pre>
            </div>

            <h3>Search Return Codes</h3>
            <div>
                <a href="http://en.wikipedia.org/wiki/List_of_HTTP_status_codes#2xx_Success">200 OK</a> response:
                <ul><li>User gave a fully-formed search query which returns a list of results in JSON format.</li></ul>

                <a href="http://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_Error">410 Gone</a> response:
                <ul><li>User gives a request for a record that had existed, but has since been deleted.</li></ul>

                <a href="http://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_Error">404 Not Found</a> response:
                <ul><li>User gives a request for a record that does not exist.</li></ul>

                <a href="http://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_Error">403 Forbidden</a> response:
                <ul><li>User gives a request for a record that exists, but is not public.</li></ul>

                <a href="http://en.wikipedia.org/wiki/List_of_HTTP_status_codes#3xx_Redirection">302 Redirect</a> response:
                <ul><li>User requests a record which has been merged with another record.</li></ul>
            </div>

            <!--BEGIN PARAMETERS-->
            <h3>How can I narrow my search?</h3>

            <p>Parameters hang off the end of a search request to narrow the results you get in your response and will get you closer to the name you are attempting to lookup.</p>

            <strong>q</strong>: <em>Optional</em> - the text respresentation of the record name you want to search.<br>
            <strong>q_type</strong>: <em>Optional</em> - the text representation of the record type. 5 types are available to filter the search, "Personal", "Organization", "Event", "Building", "Software".<br>
            <strong>callback</strong>: <em>Optional</em> - the text representation of the jsonp callback wrapper.

            <h3>Label API</h3>
            <p>The second method of searching is with the label API. The label API is essentially a quick way to determine if an authorized name exists in {{ name_app_title }}. The only two responses to this API are a 404 Not Found or a 302 Redirect.</p>
            <pre>
    $ curl "{% absolute_url "name:label" "joey-not-here" %}"
    No matching term found - authoritative, or variant - for "joey-not-here"

    $ curl -I "{% absolute_url "name:label" "thisrecordisforsureinthedatabase" %}"
    HTTP/1.0 302 FOUND
    Date: Mon, 25 Feb 2013 22:33:19 GMT
    Server: WSGIServer/0.1 Python/2.7.3
    Content-Type: text/html; charset=utf-8
    Location: {% absolute_url "name:detail" "nm0000085" %}
            </pre>

            <h3>Label Return Codes</h3>
            <div>
                <a href="http://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_Error">404 Not Found</a> response:
                <ul><li>User gives an authorized name that does not exist in the {{ name_app_title }} database.</li></ul>
                <a href="http://en.wikipedia.org/wiki/List_of_HTTP_status_codes#3xx_Redirection">302 Redirect</a> response:
                <ul>
                    <li>User gives an authorized name that does exist in the {{ name_app_title }} database. The system redirects to the corresponding record.</li>
                </ul>
            </div>
        </div>
    </div>

{% endblock %}
