Making Your First API Request

Now that you have your subscription key, you're ready to make your first request to the Document Summarization API. This guide walks you through constructing and sending a basic API request, handling the response, and ensuring successful integration.

• Endpoint URL and HTTP Method

  • Endpoint: https://api.yourdomain.com/document/summarize
  • HTTP Method: POST

  This endpoint accepts a JSON payload containing the document text or URLs and returns a summarized version based on your specifications.

• Required Headers

  • Content-Type: application/json
  • Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

  These headers ensure that the API correctly interprets your request and authenticates your access.

• Sample cURL Request

  Here's a basic example using cURL to make a POST request:

  bashCopy codecurl -X POST "https://api.yourdomain.com/document/summarize" \ -H "Content-Type: application/json" \ -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \ -d '{ "text": "Artificial Intelligence is transforming the world by enhancing various industries...", "format": "paragraph", "model": "standard" }'

• Interpreting the Response

  Upon a successful request, the API responds with a JSON object containing the summarized text and metadata. Here's an example of a successful response:

  jsonCopy code{ "summary": "AI enhances diagnostic accuracy in healthcare, optimizes treatment plans, and improves patient monitoring and care.", "success": true, "completion_time": 567 }
  • summary: The generated summary of the provided text.
  • success: Indicates whether the summarization was successful (true).
  • completion_time: Time taken to process the request, in milliseconds.

• Handling Responses in Your Application

  Depending on your programming language and framework, handling the response will vary. Here's an example in Python using the requests library:

  pythonCopy codeimport requests def summarize_text(text, format='paragraph', model='standard', tone='neutral', summary_length='standard', target_language=None): url = "https://api.yourdomain.com/document/summarize" headers = { "Content-Type": "application/json", "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY" } payload = { "text": text, "format": format, "model": model, "customization": { "tone": tone, "summary_length": summary_length } } if target_language: payload["target_language"] = target_language response = requests.post(url, headers=headers, json=payload) if response.status_code == 200: data = response.json() if data["success"]: return data["summary"] else: print("Summarization failed.") else: print(f"Error: {response.status_code} - {response.text}") # Example Usage text_to_summarize = "Artificial Intelligence is transforming the world by enhancing various industries..." summary = summarize_text(text_to_summarize, format='bullet_points', tone='formal', target_language='es') print("Summary:", summary)

• Common Pitfalls and Troubleshooting

  • Invalid Subscription Key:

    Ensure that your Ocp-Apim-Subscription-Key header contains a valid key. Invalid or expired keys will result in authentication errors (401 Unauthorized).

  • Incorrect Endpoint URL:

    Verify that you're using the correct endpoint URL and HTTP method (POST).

  • Malformed JSON Payload:

    Ensure your JSON payload is correctly structured. Missing required fields or incorrect data types can lead to 400 Bad Request errors.

  • Rate Limiting:

    Be aware of the API's rate limits to avoid 429 Too Many Requests errors. Implement retries with exponential backoff in your application.

With your first API request successfully made, explore more advanced features and customization options in the next article, "Understanding and Configuring Request Parameters."