1. Docs
  2. REST API

Shlink provides a REST API that can be used to integrate the short URLs management on any consuming system or application.

This document explains the behavior of some aspects and architectural decisions of the API.

Content negotiation

All the requests return JSON-encoded responses by default, together with semantic status codes, so it should be easy to implement client apps that consume this API.

However, if an unexpected error occurs, the system could end up returning HTML. To prevent this, always pass the header Accept: application/json.

CORS

This API supports Cross-Origin Resource Sharing out of the box (aka cross domain).

It will automatically generate the required Access-Control-* headers and manage pre-flight (OPTIONS) requests, so it can be transparently consumed from web clients hosted on different domains.

Starting with Shlink v2.5.2, the Access-Control-Allow-Origin header will be returned with value *. Previous versions used to return the value coming in the request’s Origin header instead, but some browsers might not accept that value when it’s an IP address, therefore the change.

Important: notice that Shlink will not generate the CORS headers when the request does not include an Origin header, in which case it will consider the request a server-to-server one. Browsers will always send this header when consuming an API on a different domain, so it should work transparently.

Dates

The API tries to be consistent on how dates are handled and exchanged, but these are some basic guidelines:

  • All returned dates will have the ISO-8601 format with offset from UTC (for example, 2020-01-23T05:16:00+02:00).
  • Any endpoint accepting dates will also expect the same format, usually resulting in 400 Bad Request response when this is not fulfilled.
  • Shlink also assumes all persisted dates (from visits, short URL creation, etc) belong to the timezone in which Shlink is configured.
  • Any input date will be converted to the timezone in which Shlink is configured, before using it to query data.
    • For example, if Shlink is configured in America/Los_Angeles, and the date 2020-01-23T05:16:00+02:00 is provided as part of the input for any endpoint, Shlink will first cast it to 2020-01-22T19:16:00-08:00.

Request tracing

Shlink generates a request ID on every API request. This ID is returned inside the X-Request-Id response header, and can be used to identify all the logs generated by Shlink during that request, as they are all prefixed with this ID.

If you use Shlink as part of a collection of services and need to be able to trace the whole request flow, you can also send the same X-Request-Id header in the request, and Shlink will use that value instead of generating a new one.

Further information

Continue reading the rest of the sections to understand more details of the API.