Overview of the Gini API¶

This section provides general information about the Gini API. If you want a step-by-step guide how to upload your first document and retrieve its semantic content, have a look at the getting started guide.

IPv6 compatibility¶

Gini API and User Center are accessible from legacy IPv4 and IPv6 networks. The protocol precedence depends on your operating system and configuration if both protocols are enabled.

$ host api.gini.net
api.gini.net has address 46.245.182.125
api.gini.net has IPv6 address 2a00:14e0:600:1500:d0c5::1

$ host user.gini.net
user.gini.net has address 46.245.182.124
user.gini.net has IPv6 address 2a00:14e0:600:1500:d0c5::2

Media Types¶

Custom media types are used in the API to let consumers choose the version of the data format they wish to receive. This is done by adding one or more of the following media types to the Accept header when a request is made. Media types are specific to resources, allowing them to change independently and supporting formats that other resources don’t.

The media types consumed and produced by the Gini API look like this:

application/vnd.gini.<version>+json

Warning

If you don’t specify a version in your requests, the API’s responses might change without further notice. It is strongly recommended to always specify a specific API version.

Versions¶

Currently there is one stable version of the Gini API. Future versions can be requested using a specific Accept header. Additionally, we provide a unstable incubator version of the Gini API. This is primarily for testing new extractions but may affect other parts of the Gini API as well.

v1¶

Gini API v1 is stable and will not be changed in an incompatible way. Please contact us via api@gini.net if you have any problems.

By default all requests receive data in version 1 of the API. Developers are strongly encouraged to explicitly specify the required version of the Gini API using the HTTP/1.1 Accept header:

Accept: application/vnd.gini.v1+json

incubator¶

Gini API incubator is unstable and can change at any time. We will provide new and immature features (e.g. extractions) exclusively under this Gini API version. We encourage developers to test these features and to give us feedback under api@gini.net. The incubating features are accessible by using the HTTP/1.1 Accept header:

Accept: application/vnd.gini.incubator+json

See incubator for further informations.

Authentication¶

Only authenticated users are allowed to make API requests. The Gini API uses the OAuth 2.0 protocol with bearer tokens for authentication. To use the Gini API within your application, you first have to register your application with Gini. Then your application requests an access token from the Gini Authorization Server and uses that token to access the Gini API.

See Authorization Implementation Guide for a detailed overview about the authorization process and how to implement it in your application.

Security¶

The Gini API is only accessible over HTTPS. Please make sure that your application validates the relevant X.509 certificates (e.g. common name matches hostname, issuing CA is trusted, etc.).

Client Errors¶

HTTP response codes¶

The API uses idiomatic HTTP status codes to indicate if a request was successful, and if not, whether it should be retried.

Code	Description
2xx	The request was successful.
4xx	The request was not successful. See the response body for details. Retrying with the same arguments will not work.
5xx	Some error occurred while processing the request. Please try again.

Error entity¶

The Gini API always returns a JSON object further describing the error which occurred. The JSON object consists of the following properties:

Name	Type	Description
message	string	Human consumable error description (not intended for application end-users)
requestId	string	Unique ID identifying the request. Please provide this when contacting the support.

Example¶

{
  "message": "Validation of the request entity failed",
  "requestId": "8896f9dc-260d-4133-9848-c54e5715270f"
}