You are here
API Request Reference
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.
- GET Request with a URI Parameter
- GET Request with a Content Parameter
- POST Request with a URI Parameter as 'application/x-www-form-urlencoded'
- POST Request with Content Parameter as 'application/x-www-form-urlencoded'
- POST Request with Content as 'multipart/form-data'
- POST or PUT Request with Content as the Request Body.
- POST or PUT Request with Content as the Request Body, showing labels.
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 /TOKEN/category?uri=http%3A%2F%2Fen.wikipedia.org%2Fwiki%2FNeil_young HTTP/1.1 Host: api.semantichacker.com
GET /TOKEN/category?content=the%20art%20of%20computer%20science HTTP/1.1 Host: api.semantichacker.com
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 /TOKEN/category HTTP/1.1 Host: api.semantichacker.com Content-Type: application/x-www-form-urlencoded content=the%20art%20of%20computer%20science
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--
PUT /TOKEN/category HTTP/1.1 Host: api.semantichacker.com Content-Type: text/plain the art of computer science
PUT /TOKEN/category?showLabels=true HTTP/1.1 Host: api.semantichacker.com Content-Type: text/plain the art of computer science
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.