NAV
Go Shell

API Introduction

Welcome to the speedata API. You can create PDF files using the speedata Publisher without installing it.

We have language bindings in Shell and Go. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

To authorize, use this code:

package main

import "github.com/speedata/publisher-api"

func connect() error {
	ep, err := api.NewEndpoint("username", "https://api.speedata.de")
	if err != nil {
		return err
	}
}
# Use colon at the end of the username to prevent curl from asking for
# a password
curl "https://api.speedata.de"
  -u "username:"

Make sure to replace username with your API key.

speedata API uses basic auth with no password. You must authorize on each request. Please ask for a username by sending an email to gundlach@speedata.de.

Sending a publishing request

POST a JSON file to https://api.speedata.de/v0/publish to start the publishing process

	p := ep.NewPublishRequest()
	p.AttachFile("layout.xml")
	p.AttachFile("data.xml")

	resp, err := ep.Publish(p)
	if err != nil {
		return err
	}
curl --header "Content-Type: application/json" \
  -u "username:" \
  --request POST \
  --data '{
    "files": [
        {
            "filename": "layout.xml",
            "contents": "PExheW91dAog..."
        },
        {
            "filename": "data.xml",
            "contents": "PGRhdGE+CiAg..."
        }
    ]
}' \
  https://api.speedata.de/v0/publish

The file contents is encoded base64.

The answer is in case of success a session id, such as 340416874 encoded as json: {"id":"340416874"} with a status code 201.

Getting the status of a PDF run

Send a GET request to https://api.speedata.de/v0/status/<id> and replace <id> with the session id (from /v0/publish).

ps, err := resp.Status()
if err != nil {
	return err
}
if ps.Finished != nil {
	fmt.Println("PDF done", ps.Errors, "errors occured")
	for _, e := range ps.Errormessages {
		fmt.Println("*  message", e.Error)
	}
} else {
	fmt.Println("PDF not finished yet")
}
curl \
   -u username: \
   https://api.speedata.de/v0/status/12345678

The result is a JSON file with the following fields:

Field Meaning
finished A time stamp in the format “2019-12-05T13:27:29.450219694+01:00” if the run has stopped, otherwise the string ‘null’.
errors The number of errors occured during the publishing run
errormessages An array of error messages, if any. An error message is a dictionary with the keys “code” and “error”. Se the example.
{
    "finished": "2019-12-05T13:38:42.855821194+01:00",
    "errors": 1,
    "errormessages": [
        {
            "code": 1,
            "error": "[page 1] Image \"doesnotexist.pdf\" not found!"
        }
    ]
}

Wait for a PDF to complete

Send a GET request to https://api.speedata.de/v0/wait/<id> and replace <id> with the session id (from /v0/publish).

ps, err := resp.Wait()
if err != nil {
	return err
}
// ps is the same as in /v0/status
curl \
   -u username: \
   https://api.speedata.de/v0/status/12345678

The result is the same as in /v0/status. You don't need to call wait to make sure the PDF file is finished, you can do a call to /v0/pdf/ which waits for the PDF to complete.

Getting the PDF

Do a GET request to https://api.speedata.de/v0/pdf/<id> and replace <id> with the session id (from /v0/publish).

	f, err := os.Create("out.pdf")
	if err != nil {
		return err
	}
	defer f.Close()
	// pass an io.Writer
	err = resp.GetPDF(f)
	if err != nil {
		return err
	}
	return nil
curl \
  -u "username:" \
  https://api.speedata.de/v0/pdf/12345678 \
  -o out.pdf

Errors

The speedata API uses the following error codes:

Error Code Meaning
200 Everything went well
201 The requested publishing run has been created
401 Unauthorized – Your API key is wrong
404 API URL does not exist
422 Something went wrong

In most cases, a JSON file confirming to RFC 7807 is sent to the client with the following fields:

Field Meaning
type A unique URI of an error
title A short description
detail A more detailled description of the problem
instance The request path
requestid A unique id for debugging purposes

In case of an error the server returns a JSON structured like this:

{
    "detail":"You have provided an incorrect authentification token",
    "instance":"/v0/publish",
    "title":"Not authorized",
    "type":"urn:de:speedata:api:v0:unauthorized",
    "requestid": 1234,
}