APIv1 Documentation

• Authentication
• Language
• Message Wrapper
• Changes
• Endpoints

Authentication

A user is authenticated with the API by providing their API key. The API Key can be provided by the following 2 methods:

Using Header (recommended)

The header Authorization: Bearer-Token [TOKEN] may be set in order to authenticate a user.

Using GET-parameter

For easier discovery in the Browser and for environments, where a Authorization header cannot be used (e.g. When the page is already using the header for Basic-Auth) a request may be performed by using the parameter `&api_token=[TOKEN]`

Language

The default language of the system is german. This means that if no parameter is specified german records will be returned and german language labels.

Valid languages are the following:

• de
• en
• fr
• it
• nl
• es
• cz
• dk

Record Language

The record language can be changed by providing the &language=[LANGUAGE] GET-Parameter. This will set the language for all retrieved and saved records.

Note however, that the fallback language is german. Thus if you request detailed information about a certain entity in a language that it is not available in (say &language=foobar) then the german record will be returned.

Message Wrapper

Every API-Response (no matter if sucessful or not) will be wrapped in a common wrapper containing some meta-data and the complete payload.

All properties starting with an underscore contain meta information about the request.

Links

The _links property contains URLs of other API-Endpoints that might be relevant to the developer issuing the current request.

If a List view is being requested the links nextPage and previousPage will contain URLs to the next / previous page in the paginated result list.

Attributes

The _attributes relays the properties given to the endpoint (via GET-Parameter or POST-Body) back to the requester. This can be useful when debugging a request in order to ensure the server has correctly received the request.

Additionally some properties may be populated with sane defaults or additional meta data (such as _attributes.pagination).

Errors

The _errors attribute contains information about errors that occurred during execution. Most (but not all) errors result in no payload being present.

Every error contains the following properties:

• code: Code that uniquely identifies the Error that occurred. This can either be the HTTP status code or a string such as "ERR_NO_CATEGORY"
• message: A message that is meant to be displayed to the user. This message contains information about the error and may change depending on the `locale` parameter supplied with the request.
• trace: Stack trace of where the error occurred. Only present in development mode.

Warnings

The _warnings attribute contains warnings about the current request. These warnings are meant as hints to the developer, not for user facing output.

Payload

The payload property contains the data returned by the endpoint or null if the endpoint does not return any data.

Past changes to API

Changes in 1.10

• article.show
  • Moved license up to article.index
  • Moved author up to article.index
• article.index
  • Added license
  • Added author
  • Added copyright
  • Added sourceInformationLink
• event.show
  • Moved license up to event.index
  • Moved author up to event.index
• event.index
  • Added author
  • Added copyright
  • Added sourceInformationLink
• media.show and media.index
  • Added sourceInformationLink

Changes since 1.1.0 to 1.10.0

This time we provide a list of changes since 2020-07-01.

The following request and response parameters are the main changes between these releases. Minor changes are not listed and should not be breaking. Please refer to the current API documentation for a more detailed description.

• article.index
  • New includes available
  • awards
  • externalIds
  • openingTimes
  • tourStages
  • New query options
  • withAggregates (returns some aggregated result numbers for categories, etc.)
  • withResults (option to not return the actual results)
  • New filters available
  • license
  • categoryWithSecondary
  • element
  • typeOfTour
  • city
  • externalId
  • areaZipCode
  • dynamicFieldValueSelect (filter by selected options in specific dynamic field blueprints)
  • tag
  • New article type area
  • New license community
  • New category types area and city
  • Award sets now have a type to distinguish between awards and classifications
  • New property: geocoordinates
  • New (documented) property: point (in list response, see article.show changes)
  • New (documented) property: area (in list response, see article.show changes)
  • New (documented) property: tour (in list response, see article.show changes)
• article.update
  • New property: copyright
  • New property: locationIdentifier (connect the article with a standardized location)
  • tour.trackType
  • tour.popularity renamed to tour.experience
  • tour.beauty renamed to tour.landscape
  • tour.terrain now describes the following segments: 'unknown', 'asphalt', 'gravelPath', 'nature', 'miscellaneous'
  • tour.gpsTracks.items[].trackType removed
  • tour.gpsTracks.items[].tourStages added (counts the number of stages)
  • tour.manualTrackInformation.properties[].trackType removed
  • tour.manualTrackInformation.properties[].tourStages added (counts the number of stages)
  • tour.recommendedTimeOfTravel added
  • area.properties.gettingThere added
  • area.properties.communalLink added
  • area.properties.zipCodes added
  • area.properties.communalLogo added
  • media.caption added
  • media.hasCustomCaption added
  • media.author added
  • media.sourceInformationLink added
  • media.main added
  • files.items[].file documentation added
  • contactInformation.blog added
  • openingTimes.properties.definitions.items.repeatsEveryYear added
  • relatedArticles types added:
  • tourStages
  • tourStagesVariants
  • tourInfrastructure
  • experienceMeetingPoint
• article.show
  • New query includes[] values:
  • nearbyArticles
  • nearbyEvents
  • tourStageRelations
  • awards
  • classification
  • locationIdentifiers
  • media.colors added (describes a minimal color profile of the image, useful for generating placeholders)
• event.index
  • New query include[] values:
  • distance
  • awards
  • New query filters
  • externalId
  • categoryWithSecondary
  • location
  • locationArea
  • area
  • city
  • eventType
  • element
  • distanceFrom
  • dynamicFieldValueSelect
  • tag
  • eventType added (event and experience)
  • mergeDates added (merge repeating dates of a single event into one result)
  • onDemand added
  • geocoordinates added
• event.update
  • copyright added
  • secondaryCategories added
  • relatedArticles added
  • media (see article.update)
  • dateIntervals[].bookingUrl added
  • dateIntervals[].canceled added (cancel single intervals. canceling the entire event still works.)
  • dateIntervals[].soldOut
  • locationData.type added
• event.show
  • New query include[] values:
  • awardValues

2020-W27

• Website urls in a contact information response are now automatically prefixed with a protocol.

2020-W25

• Event dates are no longer split up into regular, interval and merged since those 3 concepts do no longer exist. dates now is an array of dates at which the event is being held generated out of the dateIntervals.

2019-W50

• The event.show endpoint now returns less data with previous additions being split off into subroutes. The following information which was previously available directly on an article can now be fetched via subroutes (or include[]=...):
  • location
  • host
  • category
  • client
  • seo
  • price
• The event.index endpoint now does no longer contain information about the client. If you want information about the client of an article, please use the new event.client endpoint (or event.show with include[]=client).
• The event.index endpoint now contains only very little information for categories instead of all of it.

2019-W49

• The article and event endpoints now include more detailed client data (id, name, url and logo). Before:

  {
  "client": "123456-1234-1234-1234-123456789012"  
  }

  After:

  {
  "client": {
      "id": "123456-1234-1234-1234-123456789012",
      "name": "Foo client",
      "url": "https://www.foo-client.tld/",
      "logo": {
          "id": "758985f4-d45e-3aeb-9c47-123456789012",
          "name": "The name of this image",
          "description": "Lorem ipsum",
          "url": "http://mein.toubiz.de/path/to/file/3500f550d0605ea7393e22227eb7fa50a__5c6c3f1869123.png",
          "preview": {
              "image/png": "http://mein.toubiz.de/path/to/file/550x367q75.png",
              "image/jpeg": "http://mein.toubiz.de/path/to/file/550x367q75.jpg",
              "image/webp": "http://mein.toubiz.de/path/to/file/550x367q75.webp"
          },
          "license": null,
      },
  }  
  }

2019-W46

• The client.dynamicFieldGroups endpoint now also contains information about the category that the field group is associated with.

• client.articlePermissions and client.modulePermissions endpoints now include the name of the related entity (module or article) and it's permissions. All content previously directly under these objects has been moved into a permissions key.

  Before
  {
  "payload": {
      {moduleId}: { read: true, write: true, delete: true }
  }
  }
  
  // After:
  {
  "payload": {
      {moduleId}: {
          name: "Foo bar",
          permissions: { read: true, write: true, delete: true }
      }
  }
  }

2019-W44

• The tour type has been moved from a dynamic field to a property typeOfTour on the tour attributes of an article.

2019-W43

• The client.show endpoint now has been split up in the following sub-endpoints. The include parameter can be used on the main detail route to pull in data from the sub-endpoints similar to articles and events. The string "current" can be used to refer to the client of the current User.
  • /api/v1/client/{ID}
  • /api/v1/client/{ID}/users
  • /api/v1/client/{ID}/articles
  • /api/v1/client/{ID}/dynamicFieldGroups
  • /api/v1/client/{ID}/dynamicFieldSets
  • /api/v1/client/{ID}/modules
  • /api/v1/client/{ID}/managedClients
  • /api/v1/client/{ID}/articlePermissions
  • /api/v1/client/{ID}/modulePermissions
• relatedArticles has been added to articles.
• Article and events now have a license property containing the license under which they are available.

2019-W42

• gpsTrack and the values generated from it are now combined into a new relation in order to have easy access to both, automatically generated values as well as manual overrides. Additionally combinedTrackInformation is available when reading from the API, combining automatically extracted track information with manual overrides.

  Before:

    {
        "gpsTracks": [
            { "url": "..." }
        ],
        "kilometers": 12,
        "elevationUp": 200,
        "elevationDown": 200,
        "highestPoint": 400,
        "lowestPoint": 200
    }

  After:

    {
        "gpsTracks": [{
            "kilometers": 12.55,
            "elevationUp": 200,
            "elevationDown": 200,
            "highestPoint": 400,
            "lowestPoint": 200
        }],
        "manualTrackInformation": {
            "kilometers": 12,
            "elevationUp": null,
            "elevationDown": null,
            "highestPoint": null,
            "lowestPoint": null
        },
        "combinedTrackInformation": {
            "kilometers": 12,
            "elevationUp": 200,
            "elevationDown": 200,
            "highestPoint": 400,
            "lowestPoint": 200
        }
    }

• The price table on priceInformation will be replaced by more structured fields.

  Old:

  {
      "priceTable": [
          [ "Normalpreis", "15", "€" ],
          [ "", "20", "CHF"],
          [ "Kinder", "10", "€" ],
          [ "", "14", "CHF" ]
      ]
  }

  New:

  {
    "priceGroups": [{
        "title": "Sommerpreise",
        "comment": "Gültig April - September",
        "priceEntries": [
            {
                "title": "Normalpreis",
                "comment": "",
                "eur": 15,
                "chf": 20
            }, {
                "title": "Kinder",
                "comment": "0-12 Jahre",
                "eur": 10,
                "chf": 14
            }
        ]
    }]
  }

2019-W40

• The links on both articles and events has been replaced with a new contactInformation model that provides more straight forward fields.

  Old:

  {
      "links": [
          {
              "id": "...",
              "link": "https://twitter.com/foobar",
              "type": {
                  "id": "...",
                  "name": "Twitter"
              }
          },
          {
              "id": "...",
              "link": "https://facebook.com/foobar",
              "type": {
                  "id": "...",
                  "name": "Facebook"
              }
          }
      ]
  }

  New:

  {
      "contactInformation": {
          "id": "...",
          "website": "",
          "twitter": "https://twitter.com/foobar",
          "facebook": "https://facebook.com/foobar",
          "flickr": "",
          "youtube": "",
          "instagram": ""
      }
  }

2019-W39

• A new media.relations endpoint has been added that returns information about articles and events with relations to the given media element.
• A new article.permissions endpoint has been added that returns information about the permissions that the current user has on the article. This data can also be accessed using &include[]=permissions on the article detail route.

2019-W37

• All entities now use UUIDs instead of numerical ids. Old entities can still be referenced using their numerical ids to aid migration of tools.
• The article.index endpoint now also returns the address of a point if available.

Endpoints

• docs.json
• docs.html
• article.index
• article.update
• article.store
• article.destroy
• article.show
• article.media
• article.tags
• article.contactInformation
• article.emails
• article.fieldBlueprints
• article.fieldValues
• article.seo
• article.openingTimes
• article.phoneNumbers
• article.files
• article.additionalAddress
• article.relatedArticles
• article.nearbyArticles
• article.nearbyEvents
• article.eventsAtThisLocation
• event.index
• event.update
• event.store
• event.destroy
• event.show
• event.media
• event.files
• event.tags
• event.contactInformation
• event.printInformation
• event.seo
• event.host
• event.location
• event.category
• event.client
• event.price
• event.dates
• eventDates.indexMerged
• eventDate.show
• category.index
• category.show
• client.index
• media.index
• media.show
• media.update
• media.updateByExternalId
• media.store
• media.destroy
• media.relations
• collection.index
• collection.show
• collection.update
• collection.store
• collection.destroy
• collection.article.add
• collection.article.remove
• collection.event.add
• collection.event.remove
• audit.show
• site.index
• site.show
• site.store
• site.update
• site.destroy

docs.json

GET api/v1

Home view: Lists all endpoints with their documentation as JSON.

docs.html

GET api/v1/docs

Docs view: Lists all endpoints with their documentation as HTML.

article.index

GET api/v1/article

Lists all articles visible to the user By default invisible and unlicensed articles are hidden and can be enabled using the invisible=1 and unlicensed=1 request parameters.

Attributes

$ curl http://toubiz.local/api/v1/article?filter[category][0]=12&filter[category][1]=14

$ curl http://toubiz.local/api/v1/article?filter[category]=12,14

$ curl http://toubiz.local/api/v1/article?filter[license][0]=12&filter[license][1]=14

$ curl http://toubiz.local/api/v1/article?filter[license]=12,14

$ curl http://toubiz.local/api/v1/article?filter[categoryWithSecondary][0]=12&filter[category][1]=14

$ curl http://toubiz.local/api/v1/article?filter[categoryWithSecondary]=12,14

$ curl http://toubiz.local/api/v1/article?filter[categoryTypes][0]=area&filter[categoryTypes][1]=city

$ curl http://toubiz.local/api/v1/article?filter[categoryTypes]=area,city

{ filter: { element: 'gastronomy' } }

$ curl http://toubiz.local/api/v1/article?filter[typeOfTour]=stages_tour

$ curl http://toubiz.local/api/v1/article?filter[secondaryCategory][0]=12&filter[secondaryCategory][1]=14

$ curl http://toubiz.local/api/v1/article?filter[secondaryCategory]=12,14

curl http://toubiz.local/api/v1/article?filter[type]=tour,area,point

$ curl http://toubiz.local/api/v1/article?filter[type][0]=tour&filter[type][1]=area

curl http://toubiz.local/api/v1/article?filter[categoryType]=point

curl http://toubiz.local/api/v1/article?filter[updatedBefore]=2018-01-01
curl http://toubiz.local/api/v1/article?filter[updatedBefore]=2018-01-01T00:00:00

curl http://toubiz.local/api/v1/article?filter[updatedAfter]=2018-08-01
curl http://toubiz.local/api/v1/article?filter[updatedAfter]=2018-08-01T00:12:00

{ "filter": { "inCollection": "82a7a107-9d6b-4cbb-b9ba-ca84e04eb2ed" } }

{ "filter": { "area": "82a7a107-9d6b-4cbb-b9ba-ca84e04eb2ed" } }
{ "filter": { "area": "82a7a107-9d6b-4cbb-b9ba-ca84e04eb2ed,9d6b82a7-a107-4cbb-b9ba-ca84e04eb2ed" } }
{ "filter": { "area": { "82a7a107-9d6b-4cbb-b9ba-ca84e04eb2ed", "9d6b82a7-a107-4cbb-b9ba-ca84e04eb2ed" } } }

{ "filter": { "city": "82a7a107-9d6b-4cbb-b9ba-ca84e04eb2ed" } }
{ "filter": { "city": "82a7a107-9d6b-4cbb-b9ba-ca84e04eb2ed,9d6b82a7-a107-4cbb-b9ba-ca84e04eb2ed" } }
{ "filter": { "city": { "82a7a107-9d6b-4cbb-b9ba-ca84e04eb2ed", "9d6b82a7-a107-4cbb-b9ba-ca84e04eb2ed" } } }

{ "filter": { "inCollection": "82a7a107-9d6b-4cbb-b9ba-ca84e04eb2ed" } }

$ curl http://toubiz.local/api/v1/article?filter[externalId]=sourceName:sourceId

$ curl
http://toubiz.local/api/v1/article?filter[externalId][]=sourceName:sourceId_1&filter[externalId][]=sourceName:sourceId_2

$ curl http://toubiz.local/api/v1/article?filter[externalId]=sourceName:sourceId_1,sourceName:sourceId_2

$ curl http://toubiz.local/api/v1/article?filter[areaZipCode]=78120

$ curl http://toubiz.local/api/v1/article?filter[id][0]=...&filter[id][1]=...

$ curl http://toubiz.local/api/v1/article?filter[excludeId][0]=...&filter[excludeId][1]=...

$ curl http://toubiz.local/api/v1/article
?filter[dynamicFieldValueSelect][BLUEPRINT_UUID][0]=OPTION_UUID
&filter[dynamicFieldValueSelect][BLUEPRINT_UUID][1]=OTHER_OPTION_UUID

# Multiple tags
$ curl https://mein.toubiz.de/api/v1/[...]?filter[tag][]=foo&filter[tag][]=bar

# Multiple tags comma-separated
$ curl https://mein.toubiz.de/api/v1/[...]?filter[tag]=foo,bar

# Single tag
$ curl https://mein.toubiz.de/api/v1/[...]?filter[tag]=foo

Response

article.update

PUT api/v1/article/{article}

Updates an existing article in the database. The data structure that must be given as POST Body is the same as for the store route.

Beware: changing primaryCategory may cause losing all fieldValues which already have been set, only fields which exist in both (old and new) primaryCategory are kept. If fieldValues are set in the current request, only these ones are considered to be stored. All others will be discarded.

Attributes

{ "primaryCategory": "00632526-a779-41a2-9ffa-f7987de6d514" }

{ "primaryCategory": { "id": "00632526-a779-41a2-9ffa-f7987de6d514", ... } }

{ "client": "d8a1d47d-3192-4d8e-bf80-1b4d1404f8d1" }
{ "client": { "id": "d8a1d47d-3192-4d8e-bf80-1b4d1404f8d1", ... } }

// There are 2 fields:
// 1. test_input is a simple text input.
//    This field can have multiple values (is replicable)
// 2. test_checkbox is a checkbox list with the
//    following options: [ foo, bar, baz ]
{
     "fieldValues": {
         "test_input": [
             { "text": "first value" },
             { "text": "second value" }
         ],
         "test_checkbox": [ { "selected": [ 0, 2 ] } ]
     }
}

{
     "tags": [ "foo", "bar", "baz" ],
}

{
     "externalIds": {
         "my-external-service": "12345",
         "my-other-external-service": "foo-54321"
     }
}

{ "secondaryCategories":
    [ "00632526-a779-41a2-9ffa-f7987de6d514", "00eeb118-021f-45fc-be68-e541fbdc4ebb" ]
}

{ "secondaryCategories": [
  { "id": "00632526-a779-41a2-9ffa-f7987de6d514" },
  { "id": "00eeb118-021f-45fc-be68-e541fbdc4ebb"  }
] }

{
     "price": {
         "priceComment": "<p>Samstags sind alle Kinder bis 14 Jahre <strong>umsonst</strong></p>",
         "freeEntry": false,
         "priceTable": [
             [ "Personengruppe",                 "Preis"     ],
             [ "Kinder bis 6 Jahre",             "kostenlos" ],
             [ "Kinder bis 14 Jahre",            "7 Euro"    ],
             [ "Erwachsene",                     "15 Euro"   ],
             [ "Schüler, Studenten und Rentner", "12 Euro"   ],
         ]
     }
}

// Full update
{
     "recommendedTimeOfTravel": {
         "january": true,
         "february": true,
         "march": true,
         "april": true,
         "may": false,
         "june": false,
         "july": false,
         "august": false,
         "september": false,
         "october": false,
         "november": true,
         "december": true,
      }
}

// Partial update: Disable january but leave the rest untouched.
{
     "recommendedTimeOfTravel": {
         "january": false
     }
}

{
     "seo": {
         "metaDescription": "A super cool hotel",
         "openGraphDescription": "The best hotel in the world",
         "openGraphTitle": "Hotel Mama",
         "noIndex": false,
         "openGraphImage": { "id": 14 }
     }
}

{
     "media": [{
         "id": 42,
         "name": "This was a triumph, I'm making a note here: huge success",
         "main": true,
         "copyright": "Aperture Science",
         "altText": "we do what we must - because we can",
         "description": "for the good of all of us - except the ones who are dead"
     }]
}

{
     "externalIds": {
         "my-external-service": "12345",
         "my-other-external-service": "foo-54321"
     }
}

{ "file": { "id": 42 } }

{ "file": "https://placehold.it/500x500" }

{
     "files": [{
         "id": 42,
         "name": "Updated name",
         "description": "Updated description"
     }, {
         "file": "https://placehold.it/500x500"
     }]
}

{
     "contactInformation": {
         "twitter": "https://twitter.com/foobar"
     }
}

{
     "openingTimes": {
         "mode": "times",
         "definitions": [{
             "type": "regular",
             "openState": "times",
             "comment": "Wochenende",
             "timeRanges": [
                 { "openAt": "09:00", "closeAt": "12:00" },
                 { "openAt": "14:00", "closeAt": "18:00" },
             ],
             "monday": false,
             "tuesday": false,
             "wednesday": false,
             "thursday": false,
             "friday": false,
             "saturday": true,
             "sunday": true,
         }, {
             "type": "seasonal",
             "comment": "Zwischen den Jahren nur Sonntags abends geöffnet",
             "startOn": "2018-12-25",
             "endOn": "2019-01-01",
             "seasonalChildren": [{
                 "openState": "times",
                 "sunday": true,
                 "timeRanges": [{ "openAt": "14:00", "closeAt": "19:00" }],
             }]
         }, {
             "type": "special",
             "openState": "closed"
             "comment": "Heilig abend geschlossen",
             "appliesOn": "2018-12-24"
         }],
     }
}

{
     "type": "seasonal",
     "startOn": "2018-12-24",
     "endOn": "2019-01-01",
     "comment": "Zwischen den Jahren nur mittags geöffnet.",
     "seasonalChildren": [{
         "type": "seasonal_child",
         "openState": "times",
         "monday": true,
         "tuesday": true,
         "wednesday": true,
         "thursday": true,
         "friday": true,
         "saturday": false,
         "sunday": false,
         "timeRanges": [
             { "openAt": "14:00", "closeAt": "19:00" }
         ]
     }]
}

{
     "phoneNumbers": [
         {
             "id": 42,
             "type": "phone",
             "primary": true,
             "name": "Zentrale",
             "iso5008": "+49 123 456 78-99"
         },
         {
             "iso5008": "+49 123 456 78-12",
             "name": "Außenstelle"
         }
     ]
}

{
     "emails": [
         { "name": "test", "email": "backoffice@hotel.de" },
         {
             "id": 12,
             "name": "most important address",
             "email": "contact@hotel.de",
             "primary": true
         }
     ]
}

{
     "relatedArticles": {
         "tourStartPublicTransport": [
             { "id": "6ecfc88a-8684-47d9-9464-881a94fc63f6" }
         ]
     }
}

{
     "relatedArticles": {
         "tourStartPublicTransport": [ "6ecfc88a-8684-47d9-9464-881a94fc63f6" ]
     }
}

article.store

POST api/v1/article

Creates a new Article in the database based on the given attributes. The POST Body may contain any of the articles attributes as well as it's relations.

This action accepts the same POST Body attributes as api.v1.article.update.

article.destroy

DELETE api/v1/article/{article}

Delete the specified article.

article.show

GET api/v1/article/{article}

Fetch an article. It is possible to include relational data using the include parameter. This will add an attribute to the response payload that has the same name as the parameter (files for &include=files) that contains the response payload of the corresponding subroutes (e.g. /api/v1/article/[ID]/files).

Attributes

Response

article.media

GET api/v1/article/{article}/media

Lists all media of the given article. It is possible to access this information with include=media on the show route.

Attributes

Response

article.tags

GET api/v1/article/{article}/tags

List of all tags associated with the given article. It is possible to access this information with include=tags on the show route.

Response

article.contactInformation

GET api/v1/article/{article}/contactInformation

Displays the contact information for the article.

Response