You are here

API Request Reference

Overview

The TextWise API uses the HTTP protocol as its transport protocol and exposes all services via RESTful semantics. This enables many client types to access the API and consume its responses without much effort using standard HTTP methods. All services requests require content to be provided and the following sections detail the recommended methods.

Accepted Methods for Submitting Content

There are several methods that can be used to submit content to the API for processing by a service. Calling a service without providing content using one of the methods described below will result in an error condition. Note that all service calls to the API require an authentication token to be included as the first node in the services call path. To use the following examples, replace the term TOKEN with the actual token provided to you when you created your TextWise account.

 

How to Specify Content in a Service Call

All service calls to the API require content to be provided either directly by including the content in the call or indirectly by specifying a URI that represents the content. When you include the URI parameter in a service call, you are instructing that service to fetch the content represented by the URI. In order for the call to be successful you must ensure that the URI is valid, the content is not password protected or otherwise firewalled, and the content is text-based (E.g. not a binary, pdf, etc..) or an error will be reported. Once the content is obtained, the service will run a filtering process over the content for the purpose of removing markup (e.g.HTML tags) contained within. Once this process is complete, the service will perform its operation and return the result.
When you specify a content parameter in the service call, you are informing the service that all content to be used by the service is contained within the content parameter. The content provided in the content parameter must be less than 1000 characters if the 'HTTP Get' method was used and less than 200,000 characters if an 'HTTP Post' method is used. Generally, if the content that you need to submit to the API is greater than 1000 characters in length, you should use the HTTP Post or Put method with the content contained within the body of the request. Additionally, you can specify a filter parameter and value to force the system to apply a specific filter to the provided content.

Additional parameters for service calls can be specified to control the behavior for handling content. Please visit the Common Request Parameters page to see a complete listing of all common request parameters.

GET Request with a URI Parameter

GET /TOKEN/category?uri=http%3A%2F%2Fen.wikipedia.org%2Fwiki%2FNeil_young HTTP/1.1
Host: api.semantichacker.com

GET Request with a Content Parameter

GET /TOKEN/category?content=the%20art%20of%20computer%20science HTTP/1.1 
Host: api.semantichacker.com

POST Request with a URI Parameter as 'application/x-www-form-urlencoded'

POST /TOKEN/category HTTP/1.1
Host: api.semantichacker.com
Content-Type: application/x-www-form-urlencoded
uri=http%3A%2F%2Fen.wikipedia.org%2Fwiki%2FNeil_young

POST Request with Content Parameter as 'application/x-www-form-urlencoded'

POST /TOKEN/category HTTP/1.1 
Host: api.semantichacker.com
Content-Type: application/x-www-form-urlencoded
content=the%20art%20of%20computer%20science

POST Request with Content as 'multipart/form-data'

POST /TOKEN/category HTTP/1.1 
Host: api.semantichacker.com
Content-Type: multipart/form-data; boundary=x42x 

--x42x
Content-Disposition: form-data; name="file"; filename="textfile.txt"
Content-Type: text/plain

the art of computer science
--x42x--

POST or PUT Request with Content as the Request Body.

PUT /TOKEN/category HTTP/1.1
Host: api.semantichacker.com
Content-Type: text/plain

the art of computer science

POST or PUT Request with Content as the Request Body, showing labels.

PUT /TOKEN/category?showLabels=true HTTP/1.1
Host: api.semantichacker.com
Content-Type: text/plain

the art of computer science

Load Limiting

The TextWise API is a shared web resource. To be fair to everyone using the API, we have limited how quickly any single user can make requests. The system is configured to allow for a maximum of 5 requests per second. If a user makes requests too quickly, they will be sent an 'over load limit' as defined in the API Response Reference. At this point, the program making requests should be designed to pause for at least 2 seconds. After pausing, requests will again be processed normally. For maximum throughput you should design your application to send no more than 5 requests per second.