GET(Polling) and Callback

This document describes the difference between GET (polling) and CALLBACK among the when used as response methods of APIs that provide voice recognition (STT) services. This guide is designed to help developers and service representatives utilize the API effectively.

1. GET(Polling) Method

Conceptual Description

The polling method is an HTTP method used by clients to request information from servers. The client sends a request for a particular resource and the server returns a response for that resource. It is primarily used to read data, and it is a secure request that does not affect the server.

Structure of Polling Request

• HTTP Method: GET
• URL: URL identifying resources to request (e.g. https://apis.daglo.ai/stt/v1/async/transcripts/{rid})
• Query parameters: Additional information required for request (use as needed)

Example

GET https://apis.daglo.ai/stt/v1/async/transcripts/12345

Response Example

{
  "status": "transcribed",
  "sttResults": [
    "transcript": "Hello, this is a sample transcript."
  ]
}

Schematic

Client -- (GET) --> Server
Client <--(Response)-- Server

2. CALLBACK Method

Conceptual Description

The CALLBACK method is a way for servers to asynchronously deliver data to clients. The client provides a callback URL when sending the initial request to the server. Upon request completion, the server sends the result of the request to the callback URL. It is useful for asynchronous operations, eliminating the need for clients to constantly check the status with the server.

Structure of CALLBACK Request

• HTTP Method: POST (when registering callback URL)
• URL: Callback URL to which the client will receive results
• Body: Data required for request (e.g. transcript result)

Example

1. Include a callback URL when the client sends an asynchronous request.

   {
       // ...
       "callback": {
           "url": "https://client.example.com/callback",
           "headers": { "<Header1_KEY>": "<Header1_Value>" } // Optional
       }
   }

2. Server completes processing and sends results to callback URL.

   POST https://client.example.com/callback
   Content-Type: application/json
   
   {
     "status": "transcribed",
     "sttResults": [
       "transcript": "Hello, this is a sample transcript."
     ]
   }

Schematic

Client -- (POST request, with callback URL) --> Server
(Processing)
Server -- (Results) --> Client (POST to Callback URL)

3. The difference between the GET (Polling) method and the CALLBACK method

Item	GET (Polling) Method	CALLBACK Method
Request Method	Client receives direct response after request	Client provides callback URL on request. Server sends results asynchronously.
Data Delivery	Immediate Response to Request	Asynchronous delivery to Callback URL after processing is completed
Use Cases	Simple inquiry, immediate response	Asynchronous processing, long latency action
Network load	Requires clients to periodically check health	Servers deliver results in one callback
Implementation Complexity	Relatively simple	Needs to consider Callback URL management and security

4. Conclusion

The GET (polling) method and the CALLBACK method have their own advantages and disadvantages. Depending on the needs of the user and the characteristics of the system, the appropriate method can be selected and utilized. The GET (polling) method is simple and intuitive, and is suitable when immediate response is needed. The CALLBACK method is advantageous for asynchronous tasks, and has the advantage of not having to constantly check the status of the request.

5. CALLBACK Server Implementation

The CALLBACK server is configured to allow clients to receive data asynchronously from the server. To do this, the client provides the callback URL to the server, which sends the result to the URL after the job is completed. The method of configuring the CALLBACK server consists of the following steps.

1) Server Settings

Select a server framework

To implement the CALLBACK server, you must select the appropriate server framework. For example, you can use Python's Flask, Node.js' Express, Java's Spring Boot, and so on.

2) Callback Endpoint Setting

Endpoint definition

Defines the endpoint to be used as a callback URL, which must be prepared to receive the result as a POST request after the operation is completed.

Example (Python Flask)

text

from flask import Flask, request

app = Flask(__name__)

@app.route('/callback', methods=['POST'])
def stt_callback():
    data = request.get_json()
    # Received data processing logic
    print(data['rid'])
    print(data['status'])
    print(data['sttResults'])

    return 'OK'

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

3) Security Settings

Certification and Authorization

Because the callback URL is externally accessible, security needs to be strengthened through authentication and authorization. For this, requests can be authenticated using JWT tokens, API keys, etc.

Example (JWT token authentication)

text

Copy python code
import jwt

SECRET_KEY = 'your_secret_key'

def verify_token(token):
    try:
        jwt.decode(token, SECRET_KEY, algorithms=['HS256'])
        return True
    except jwt.ExpiredSignatureError:
        return False
    except jwt.InvalidTokenError:
        return False

@app.route('/callback', methods=['POST'])
def callback():
    token = request.headers.get('Authorization')
    if not token or not verify_token(token):
        return jsonify({'message': 'Unauthorized'}), 401

    data = request.get_json()
    # Add callback data processing logic

    return jsonify({'message': 'Callback received successfully'}), 200

4) Logging and monitoring

Request logging

Log callback requests so that they can be debugged in the event of a problem.

Example (add logging)

text

Copy python code
import logging

logging.basicConfig(level=logging.INFO)

@app.route('/callback', methods=['POST'])
def callback():
    data = request.get_json()
    logging.info(f"Received callback with data: {data}")

    # Add callback data processing logic

    return jsonify({'message': 'Callback received successfully'}), 200

5) Testing and distribution

Test

Test the callback server sufficiently to ensure that it works correctly in all scenarios; verify stability through unit testing, integrated testing, and more.

Deployment

When tests are complete, the callback server is deployed in a production environment. This process ensures stable operation considering load balancing and scaling.

Conclusion

The way a CALLBACK server is configured should be designed to allow clients to receive data asynchronously. This requires steps such as server framework selection, endpoint setup, security enhancement, logging and monitoring, testing, and deployment. This process enables a reliable and secure CALLBACK server to be implemented.

Update History

• 20240902 ver1.0 API document has been created.