REST APIs

Skip to end of metadata
Go to start of metadata
Table of Contents

Introduction

S4 provides various REST APIs for processing individual documents in real time and for querying Linked Open Datasets (Freebase, GeoNames and DBpedia) via SPARQL.

  • All S4 APIs requests require an API key for HTTP basic authentication. The API keys are private for each user account and can be generated via the S4 Management Console.
  • The RESTful services accept JSON as input and return JSON as output.
  • The service endpoints for the various S4 APIs are listed on the Service Endpoints page.
  • S4 services support gzip compression of the service's response. You can enable it by setting an Accept-Encoding: gzip HTTP header.

Request HTTP headers, Request and Response Formats

  • information about the text analytics services request/response formats is available on the Text Analytics page
  • information about the knowledge graph service request/response formats is available on the Knowledge Graphs page
  • information about the fully managed database-as-a-service request/response formats is available on Fully Managed Database the page

The S4 REST services support the following HTTP request methods:

S4 service
GET
POST
PUT
DELETE
all text analytics services
-
  • submit a document for processing
-
-
knowledge graph service
  • SPARQL query
  • SPARQL query
-
-
self- or fully managed RDF graph databases (OpenRDF REST API)
  • list repositories
  • list named graphs / contexts / namespaces
  • query data
  • read data
  • get the database configuration
  • query data
  • update data (RDF document)
  • update data (SPARQL 1.1 Update)
  • create repositories
  • create namespaces and contexts
  • update data (RDF document)
  • update the database configuration
  • delete repositories
  • delete named graphs
  • delete namespaces and contexts
  • delete data

SSL Encryption

All S4 REST APIs as well as the S4 Management Console utilise a transport level encryption via SSL. Unencrypted HTTP access is not supported.

HTTP Compression

All S4 services support gzip compression of the service response for better performance. It is recommended that you enable the compression by setting an Accept-Encoding: gzip HTTP header.

Error messages

In case of a problem with the correct execution of the request, an error response is returned with an HTTP status code, specifying the type of the error (as described below), as well as a human readable error message.

Status Code
Description
40x Problems with the user input
50x Errors during the execution of the request

If the user has exceeded his free quota, the error response will be: 429 "Too Many Requests"

API Keys

The access to the S4 REST API requires a private API key, which consists of two randomly generated parts, the "key ID" and "password". Each customer account can generate an unlimited number of API keys (for different applications or users) and each API key can be enabled/disabled or deleted as necessary.

To create an API key, go to the "API Key Management" section of the S4 Management Console at http://s4.ontotext.com and click the "Generate a new API key" button.

Note: You must store the key ID and password at a secure location. If you lose your API key password, you will not be able to recover it. You will need to delete your existing key and generate a new one.

Usage Quotas

Currently, S4 provides the following free quotas:

S4 service usage limits / period
Text analytics (news, news classifier, life science and social media) 250 MB of data processed / monthly
Image tagging & classification in web pages (via Imagga API)
2,000 images / monthly
access to knowledge graphs (Freebase/Wikidata, DBpedia and GeoNames) 5,000 SPARQL queries / monthly
RDF graph database in the Cloud (self-managed) no limits (the customer is in control of how the service is used)
RDF graph database in the Cloud (fully managed)
1,000,000 triples stored in the database

Sample Code

You can find code samples showing how you to access the service from various programming languages at https://github.com/Ontotext-AD/S4

Sample code is available in the following programming languages:

  • Java
  • C#
  • cURL
  • Python (using urllib2)
  • NodeJS
  • JavaScript
  • Groovy (using HttpBuilder)
  • PHP

SDKs

We provide Java and C# SDKs to make accessing S4 services and application development easier for Java/C# developers.

Swagger

The Swagger documentation for the REST APIs is available at http://swagger.s4.ontotext.com/

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.