The asynchronous HTTP interface

Usage models

When you work with the service's asynchronous HTTP interface, you can elect to learn about job status and receive results in the following ways:

• By using callback notifications:
  1. Call the POST /v1/register_callback method to register a callback URL with the service. You can provide an optional user-specified secret string to enable authentication and data integrity for callbacks that are sent to the URL.
  2. Call the POST /v1/recognitions method with an already registered callback URL to which the service sends notifications when the status of the job changes. You specify a list of events of which to be notified. By default, the service sends notifications when a job is started, when it is complete, and if an error occurs. You can also request the results of the request in the completion notification. Otherwise, you need to use the GET /v1/recognitions/{id} method to retrieve the results.
• By polling the service:
  1. Call the POST /v1/recognitions method without a callback URL, events, or a user token.
  2. Periodically call the GET /v1/recognitions method to check the status of the most recent jobs or the GET /v1/recognitions/{id} method to check the status of a specific job.
  3. If you check job status with the GET /v1/recognitions method, call the GET /v1/recognitions/{id} method to retrieve the results of the job once it is complete.

The two approaches can be used together. You can still poll the service to obtain the latest status for a job that is created with a callback URL. For example, you might want to obtain the status of a job if notifications are taking a while to arrive. You might also check the status if you suspect that you missed one or more notifications due to a service or network error.

Registering a callback URL

You register a callback URL by calling the POST /v1/register_callback method. Once you register a callback URL, you can use it to receive notifications for an indefinite number of jobs. The registration process comprises four steps:

1. You call the POST /v1/register_callback method and pass a callback URL. Optionally, you can also specify a user-specified secret. The service uses the secret to compute keyed-hash message authentication code (HMAC) Secure Hash Algorithm 1 (SHA1) signatures for authentication and data integrity. The following example registers a user callback that responds at the URL http://{user_callback_path}/results. The call includes a user secret of ThisIsMySecret.

   IBM Cloud

   curl -X POST -u "apikey:{apikey}" \
   "{url}/v1/register_callback?callback_url=http://{user_callback_path}/results&user_secret=ThisIsMySecret"
   

   IBM Cloud Pak for Data

   curl -X POST \
   --header "Authorization: Bearer {token}" \
   "{url}/v1/register_callback?callback_url=http://{user_callback_path}/results&user_secret=ThisIsMySecret"
   

2. The service attempts to validate, or allowlist, the callback URL if it is not already registered by sending a GET request to the callback URL. The service passes a random alphanumeric challenge string via the challenge_string query parameter of the request. The request includes an Accept header that specifies text/plain as the required response type.

   If the call to the register_callback method included a user secret, the GET request from the service also includes an X-Callback-Signature header that specifies the HMAC-SHA1 signature of the challenge string. The service calculates the signature by using the user secret as the key.

   GET http://{user_callback_path}/results?challenge_string=n9ArPGMQ36Hiu7QC
   header: X-Callback-Signature {HMAC-SHA1_signature}
   

3. You respond to the GET request from the service with status code 200. Include the challenge string that was sent by the service in the response. Include the string in plain text in the body of the response, and set the Content-Type response header to text/plain.

   If the initial POST request included a user secret, you can calculate an HMAC-SHA1 signature of the challenge string by using the secret as the key. If the GET request was sent by the service, the signature matches the value specified by the X-Callback-Signature header.

   response code: 200 OK
   body: n9ArPGMQ36Hiu7QC
   

4. The service checks whether the challenge string is returned in the body of the response to its GET request. If it is, the service allowlists the callback URL and responds to your original POST request with status code 201. The body of the response includes a JSON object with a status field that has the value created and a url field that has the value of your callback URL.

   response code: 201 Created
   body: {
     "status": "created",
     "url": "http://{user_callback_path}/results"
   }
   

The service sends only a single GET request to a callback URL during the registration process. The service must receive a reply with response code 200 that includes the challenge string in its body within five seconds. Otherwise, it does not allowlist the URL. Instead, it sends status code 400 in response to the POST /v1/register_callback request. If the callback URL was already successfully allowlisted, the service sends status code 200 in response to the initial POST request.

curl -X POST -u "apikey:{apikey}" \
"{url}/v1/unregister_callback?callback_url=http://{user_callback_path}/results"

curl -X POST \
--header "Authorization: Bearer {token}" \
"{url}/v1/unregister_callback?callback_url=http://{user_callback_path}/results"

Creating a job

You create a recognition job by calling the POST /v1/recognitions method. How you learn the status and results of the job depends on the approach you use and the parameters you pass:

• To use callback notifications, include the callback_url query parameter to specify a URL to which the service is to send callback notifications when the status of the job changes. You can also specify the following optional query parameters:
  • events to subscribe to a list of notification events. By default, the service sends callback notifications when the job is started (the recognitions.started event), when the job is complete (the recognitions.completed event), and if an error occurs (the recognitions.failed event). You can specify a subset of the events or use the recognitions.completed_with_results event instead of the recognitions.completed event to include the results with the job-completed notification.
  • user_token to specify a string that is to be included with each notification for the job. Because you can use the same callback URL with an indefinite number of jobs, you can leverage user tokens to differentiate notifications for different jobs.
• To use polling, omit the callback_url, events, and user_token query parameters. You must then use the GET /v1/recognitions or GET /v1/recognitions/{id} methods to check the status of the job, using the latter to retrieve the results when the job is complete.

In both cases, you can include the results_ttl query parameter to specify the number of minutes for which the results are to remain available after the job completes. The new job is owned by the instance of the service whose credentials are used to create it.

In addition to the previous parameters, which are specific to the asynchronous interface, the POST /v1/recognitions method supports most of the same parameters as the WebSocket and synchronous HTTP interfaces. For more information, see the Parameter summary.

{
  "id": "{job_id}",
  "event": "{recognitions_status}",
  "user_token": "{user_token}"
}

from hashlib import sha1
import hmac
hashed = hmac.new(user_secret, notification_payload, sha1)
signature = hashed.digest().encode("base64").rstrip('\n')

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: audio/flac" \
--data-binary @{path}audio-file.flac \
"{url}/v1/recognitions?callback_url=http://{user_callback_path}/results&user_token=job25&timestamps=true"

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: audio/flac" \
--data-binary @{path}audio-file.flac \
"{url}/v1/recognitions?callback_url=http://{user_callback_path}/results&user_token=job25&timestamps=true"

{
  "created": "2016-08-17T19:15:17.926Z",
  "id": "4bd734c0-e575-21f3-de03-f932aa0468a0",
  "url": "{url}/v1/recognitions/4bd734c0-e575-21f3-de03-f932aa0468a0",
  "status": "waiting"
}

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: audio/wav" \
--data-binary @{path}audio-file.wav \
"{url}/v1/recognitions?timestamps=true"

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: audio/wav" \
--data-binary @{path}audio-file.wav \
"{url}/v1/recognitions?timestamps=true"

{
  "created": "2016-08-17T19:13:23.622Z",
  "id": "4bb1dca0-f6b1-11e5-80bc-71fb7b058b20",
  "url": "{url}/v1/recognitions/4bb1dca0-f6b1-11e5-80bc-71fb7b058b20",
  "status": "processing"
}

Checking the status and retrieving the results of a job

You call the GET /v1/recognitions/{id} method to check the status of the job that is specified with the id path parameter. The response always includes the ID and status of the job and its creation and update times. If the status is completed, the response also includes the results of the recognition request.

The GET /v1/recognitions/{id} method is the only way to retrieve job results if

• The job was submitted without a callback URL.
• The job was submitted with a callback URL but without specifying the recognitions.completed_with_results event.
• The job is not one of the 100 latest outstanding jobs. When you omit the id path parameter, only the 100 latest jobs are returned.

However, you can still use the method to retrieve the results for a job that specified a callback URL and the recognitions.completed_with_results event. You can retrieve the results for any job as many times as you want while they remain available. A job and its results remain available until you delete them with the DELETE /v1/recognitions/{id} method or until the job's time to live expires, whichever comes first. By default, results expire after one week unless you specify a different time to live with the results_ttl parameter of the POST /v1/recognitions method.

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/recognitions/{job_id}"

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/recognitions/{job_id}"

{
  "id": "4bb1dca0-f6b1-11e5-80bc-71fb7b058b20",
  "created": "2016-08-17T19:13:23.622Z",
  "updated": "2016-08-17T19:13:24.434Z",
  "status": "processing"
}

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/recognitions/{job_id}"

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/recognitions/{job_id}"

{
  "id": "398fcd80-330a-22ba-93ce-1a73f454dd98",
  "results": [
    {
      "result_index": 0,
      "results": [
        {
          "final": true,
          "alternatives": [
            {
              "transcript": "several tornadoes touch down as a line of severe thunderstorms swept through Colorado on Sunday ",
              "timestamps": [
                [
                  "several",
                  1,
                  1.52
                ],
                [
                  "tornadoes",
                  1.52,
                  2.15
                ],
                . . .
                [
                  "Sunday",
                  5.74,
                  6.33
                ]
              ],
              "confidence": 0.96
            }
          ]
        }
      ]
    }
  ],
  "created": "2016-08-17T19:11:04.298Z",
  "updated": "2016-08-17T19:11:16.003Z",
  "status": "completed"
}

Checking the status of the latest jobs

You call the GET /v1/recognitions method to check the status of the latest jobs. The method returns the status of the most recent 100 outstanding jobs that are associated with the credentials with which it is called. The method returns the ID and status of each job, along with its creation and update times. If a job was created with a callback URL and a user token, the method also returns the user token for the job.

The response includes one of the following states:

• waiting if the service is preparing the job for processing. This status is the initial state of all jobs. The job remains in this state until the service has the capacity to begin processing it.
• processing if the service is actively processing the job.
• completed if the service has finished processing the job. If the job specified a callback URL and the event recognitions.completed_with_results, the service sent the results with the callback notification. Otherwise, use the GET /v1/recognitions/{id} method to obtain the results.
• failed if the job failed for some reason.

A job and its results remain available until you delete them with the DELETE /v1/recognitions/{id} method or until the job's time to live expires, whichever comes first.

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/recognitions"

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/recognitions"

{
  "recognitions": [
    {
      "id": "4bd734c0-e575-21f3-de03-f932aa0468a0",
      "created": "2016-08-17T19:15:17.926Z",
      "updated": "2016-08-17T19:15:17.926Z",
      "status": "waiting",
      "user_token": "job25"
    },
    {
      "id": "4bb1dca0-f6b1-11e5-80bc-71fb7b058b20",
      "created": "2016-08-17T19:13:23.622Z",
      "updated": "2016-08-17T19:13:24.434Z",
      "status": "processing"
    },
    {
      "id": "398fcd80-330a-22ba-93ce-1a73f454dd98",
      "created": "2016-08-17T19:11:04.298Z",
      "updated": "2016-08-17T19:11:16.003Z",
      "status": "completed"
    }
  ]
}

Deleting a job

You can use the DELETE /v1/recognitions/{id} method to delete the job that is specified with the id path parameter. You typically delete a job after you obtain its results from the service. Once you delete a job, its results are no longer available. You cannot delete a job that the service is actively processing.

By default, the service maintains the results of each job until the job's time to live expires. The default time to live is one week, but you can use the results_ttl parameter of the POST /v1/recognitions method to specify the number of minutes that the service is to maintain the results.

curl -X DELETE -u "apikey:{apikey}" \
"{url}/v1/recognitions/{job_id}"

curl -X DELETE \
--header "Authorization: Bearer {token}" \
"{url}/v1/recognitions/{job_id}"