.. _restful-label:

RESTful API
-----------

.. note:: Stellen Sie sicher, dass alle Anfragen per ``https`` gestellt werden. Unverschlüsselte ``http`` Anfragen werden abgewiesen.

.. _hash-label:

hash
^^^^

.. http:post:: /api/v1/hash

    Fügt einen oder mehrere neue Einträge hinzu. Liefert die gespeicherte Zeit und, ob der Hash neu ist.
    Der Wert von invaliden Hashes ist "invalid Hash". Falls bei der Anfrage kein valider Hash übergeben wurde, wird
    Fehlercode 422 zurück gegeben.

    Die Einträge können sowohl als json im post body übergeben werden, als auch im "form-format".

    .. sourcecode:: json

        {
            hash: [
                "deadbeef6d6ebd39c8107d219b46832ca31530328efc43dc41f37aec1586f58e",
                "4c6cb9cb44bf441d256813e3eef602d4319380b04c1e05087b3163fa66cff6da"
                ]
        }

    **Beispiel Curl**:

    .. sourcecode:: bash

        curl --user $API_KEY:unused https://notar.direct/api/v1/hash -d "hash=deadbeef6d6ebd39c8107d219b46832ca31530328efc43dc41f37aec1586f58e" -d "hash=4c6cb9cb44bf441d256813e3eef602d4319380b04c1e05087b3163fa66cff6da" -d "hash=not_a_hash"-X POST


    **Beispiel Python**:

    .. sourcecode:: python

        import requests
        from requests.auth import HTTPBasicAuth

        api_key = "your_API_key"
        hashes = ["deadbeef6d6ebd39c8107d219b46832ca31530328efc43dc41f37aec1586f58e",
                  "4c6cb9cb44bf441d256813e3eef602d4319380b04c1e05087b3163fa66cff6da",
                  "not_a_hash"]

        r = requests.post("https://notar.direct/api/v1/hash",
                          auth=HTTPBasicAuth(api_key, ''),
                          json={"hash": hashes})

        assert(r.status_code == 201)


    **Beispiel JavaScript/jQuery**:

    .. sourcecode:: javascript

        function ajaxPost(uri, data)
        {
            var token = "Your_API_Key";
            var request = {
                url: uri,
                type: "POST",
                contentType: "application/json",
                accepts: "application/json",
                cache: false,
                dataType: 'json',
                data: JSON.stringify(data),
                beforeSend: function(xhr) {
                    xhr.setRequestHeader("Authorization",
                                         "Basic " + btoa(token+":x"));
                }
            };
            return $.ajax(request);
        }

        var hashes = ["deadbeef6d6ebd39c8107d219b46832ca31530328efc43dc41f37aec1586f58e",
                      "4c6cb9cb44bf441d256813e3eef602d4319380b04c1e05087b3163fa66cff6da",
                      "not_a_hash"];

        ajaxPost("https://notar.direct/api/v1/hash", hashes);


    **Response**:

    .. sourcecode:: json

        {
            "deadbeef6d6ebd39c8107d219b46832ca31530328efc43dc41f37aec1586f58": {
                "date": "2015-11-15T09:39:08",
                "new": false
            },
            "4c6cb9cb44bf441d256813e3eef602d4319380b04c1e05087b3163fa66cff6da": {
                "date": "2015-11-15T09:33:12",
                "new": false
            }
            "not_a_hash": "invalid Hash"
        }


    :param hash: Hash der Datei
    :type hash: string

    :reqheader Authorization: Anmeldedaten wie in :ref:`auth-label` beschrieben

    :status 201:
    :status 401: wenn die Authentifizierung fehlschlägt
    :status 422: wenn kein einziger valider Hash übertragen wurde


.. _check-label:

check
^^^^^

    .. http:get:: /api/v1/check

        Sucht den timestamp zu dem gegebenen ``hash``, mehrere können gleichzeitig abgefragt werden.

        **Beispiel Curl**:

        .. sourcecode:: bash

            curl --user $API_KEY:unused https://notar.direct/api/v1/check -d "hash=4c6cb9cb44bf441d256813e3eef602d4319380b04c1e05087b3163fa66cff6da&hash=a99a315b6d6ebd39c8107d219b46832ca31530328efc43dc41f37aec1586f58e" -X GET

        **Beispiel Python**:

        .. sourcecode:: python

            import requests
            from requests.auth import HTTPBasicAuth

            api_key = "Your_API_Key"
            hashes = [
                        "4c6cb9cb44bf441d256813e3eef602d4319380b04c1e05087b3163fa66cff6da",
                        "a99a315b6d6ebd39c8107d219b46832ca31530328efc43dc41f37aec1586f58e"
                     ]

            r = requests.get("https://notar.direct/api/v1/check",
                             auth=HTTPBasicAuth(api_key, ''),
                             params={"hash": hashes})

            assert(r.status_code == 200)

        **Response**:
        
        .. sourcecode:: json

            {
                "4b6cb9cb44bf441d256813e3eef602d4319380b04c1e05087b3163fa66cff6da": "",
                "a99a315b6d6ebd39c8107d219b46832ca31530328efc43dc41f37aec1586f58e": "2015-12-24T08:43:39.855220+00:00"
            }

        Zurückgegeben wird ein JSON struct, jeden abgefragten ``hash`` enthält.
        Falls der abfragende User diesen gespeichert hat, wird das Datum der
        ersten Speicherung dazu ausgegeben, wenn er unbekannt fuer diesen User
        ist, wird ein leerer String ausgegeben.

        :param hash: der sha256 Hash der Datei, kann mehrfach angehängt werden, damit mehrere Hashes abgefragt werden
        :type hash: string

        :reqheader Authorization: Anmeldedaten wie in :ref:`auth-label` beschrieben

        :status 200: gibt die Daten als json wieder
        :status 401: wenn die Authentifizierung fehlschlägt

.. _token-label:

token
^^^^^

.. http:get:: /api/v1/token

    Liefert (nach erfolgreicher Authentifizierung) ein 10 Minuten gültiges Token, das zur
    Authentifizierung genutzt werden kann.

    .. sourcecode:: bash

        curl --user $API_KEY:unused https://notar.direct/api/v1/token -X GET

    :reqheader Authorization: Anmeldedaten wie in :ref:`auth-label` beschrieben

    :status 200: Token wurde erfolgreich erzeugt
    :status 401: wenn die Authentifizierung fehlschlägt
    :status 404: wenn diese Mandantenkennung nicht existiert

.. _upload-label:

upload
^^^^^^

.. http:get:: /api/v1/upload

    Lädt eine oder mehrere Dateien hoch, die auf dem Server gespeichert werden.

    .. sourcecode:: bash

        curl --user $API_KEY:unused https://notar.direct/api/v1/upload F file1=@/path/to/file.pdf -F file2=@/path/to/second/file.png -X POST

    .. sourcecode:: json
        [
            {
                "sha256": "7d7e8b5b1f3f7497111dd2c5433d143fb18287ffa751b729ac46133cf5ec62b6",
                 "new": false,
                 "size": 157197,  // size in Bytes
                 "name": "file.pdf"
            },
            {
                "sha256": "e8ff8c00e2fd483a0193a677e69d8ea87906756716f172b293e5c10e28696468",
                "new": true,
                "size": 33549265,
                "name": "file.png"
            }
        ]

    :reqheader Authorization: Anmeldedaten wie in :ref:`auth-label` beschrieben

    :status 201: Dateien wurden erfolgreich gespeichert
    :status 401: wenn die Authentifizierung fehlschlägt
    :status 404: wenn diese Mandantenkennung nicht existiert oder die Speicherung fehlschlägt