Using the service - TextKing/textking-api GitHub Wiki

Accessing the service

All requests to the TEXTKING Rest Service are below the base URL https://api.textking.com/v1, where v1 specifies the version of the service.

Selecting the data format

The TEXTKING API supports both JSON and XML as a data format. You should always include an Accept HTTP header to specify the format you want to use. For JSON use Accept: application/json, for XML use Accept: application/xml.

If you pass data to the service, e.g. to create a new project, you should also pass your data either in JSON or XML format and specify the data format with the Content-Type header.

Selecting the response language

Similar to selecting the data format you can select the language in which localized resources are returned. Some resources, such as language and topic names, are available in multiple languages (English and German at the moment). To select the language, include the Accept-Language HTTP header in your request. E.g. the following request will return the first two topics in German:

GET /v1/topics?per_page=2 HTTP/1.1
Host: api.textking.com
Authorization: Bearer youraccesstokenhere
Accept: application/json
Accept-Language: de

JSON response:

{
    "items": [
        {
            "id": "49353ab0-fdbf-4e1c-a063-cdf4aad98782",
            "name": "Allgemein",
            "localization_language": "deu",
            "links": [
                {
                    "rel": "self",
                    "href": "https://api.textking.dev/v1/topic/49353ab0-fdbf-4e1c-a063-cdf4aad98782"
                }
            ]
        },
        {
            "id": "c68cd090-a5ae-4b5e-b514-f70046177844",
            "name": "Bauwesen, Immobilien",
            "localization_language": "deu",
            "links": [
                {
                    "rel": "self",
                    "href": "https://api.textking.dev/v1/topic/c68cd090-a5ae-4b5e-b514-f70046177844"
                }
            ]
        }
    ],
    "page": 1,
    "per_page": 2,
    "total": 15,
    "links": [
        {
            "rel": "self",
            "href": "https://api.textking.dev/v1/topics?page=1&per_page=2"
        },
        {
            "rel": "next",
            "href": "https://api.textking.dev/v1/topics?page=2&per_page=2"
        }
    ]
}

Error handling

In case of an error the service will return a HTTP error code together with a error detail object containing more information. The errors depend on the resource endpoint and are described for each endpoint in the documentation. There are also a couple of general errors:

HTTP Status Code	Description
401 Unauthorized	The `Authorization` is missing or the access token is invalid.
404 Not Found	The requested resource was not found.
406 Not Acceptable	The content type specified by the `Accept` header is not supported.

The format of the error response can be either JSON or XML, depending on the Accept header format. Sample JSON error:

{
    "description": "Missing access token."
}

And the same error in XML format:

<error xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.textking.dev/v1/">
    <description>Missing access token.</description>
</error>