REST APIv3 Documentation

Sending the Development Header

To prevent tracking of API calls during tests and development, use the "X-Integreat-Development" header. Example:

curl -H "X-Integreat-Development: true"  \
https://cms.integreat-app.de/testumgebung/de/wp-json/extensions/v3/pages

Locations/Multisites/Instances

REQUEST

Get all locations (both live and hidden)

GET /wp-json/extensions/v3/sites HTTP/1.1
Host: web.integreat-app.de

RESPONSE

[
  {
    "id": Number,                    // id of location
    "name": String,                  // prefix + name of location
    "icon": String,                  // url to icon
    "cover_image": String,           // url to cover_image
    "color": String,                 // hex-representation of main color (currently #FFA000)
    "path": String,                  // path to site (without host)
    "description": String,           // description of location
    "live": Boolean,                 // determines if the location is live or hidden
    "prefix": String|null,           // prefix of location name, e.g. "Stadt"
    "name_without_prefix": String,   // location name without prefix
    "plz": Number|null,              // plz (Postleitzahl/ZIP) of location
    "extras": Boolean,               // true if at least one extra is enabled
    "events": Boolean,               // true if events are enabled
    "push-notifications": Boolean,   // true if push-notifications are enabled
    "longitude": Number|null,        // longitude of the geographic center of the city/county
    "latitude": Number|null,         // latitude of the geographic center of the city/county
    "aliases": null|{                     // value can also be NULL
        "alias1": {                  // name of a city alias (smaller municipality within a county)
            "longitude": Number,          // longitude of the geographic center of the city/county alias
            "latitude": Number,           // latitude of the geographic center of the city/county alias
        },
        ...
     }
  },
  ...
]

REQUEST

Get all live or hidden sites

GET /wp-json/extensions/v3/sites/{live|hidden} HTTP/1.1
Host: web.integreat-app.de

RESPONSE

[
  {
    "id": Number,                    // id of location
    "name": String,                  // prefix + name of location
    "icon": String,                  // url to icon
    "cover_image": String,           // url to cover_image
    "color": String,                 // hex-representation of main color (currently #FFA000)
    "path": String,                  // path to site (without host)
    "description": String            // usually the same as "name"
    "prefix": String|null            // prefix of location name, e.g. "Stadt"
    "name_without_prefix": String    // location name without prefix
    "plz": Number|null               // plz (Postleitzahl/ZIP) of location
    "extras": Boolean                // true if at least one extra is enabled
    "events": Boolean                // true if events are enabled
    "push-notifications": Boolean    // true if push-notifications are enabled
  },
  ...
]

Languages

Get all available languages of a location

REQUEST

GET /{site}/de/wp-json/extensions/v3/languages HTTP/1.1
Host: web.integreat-app.de

RESPONSE

[
  {
    "id": Number,
    "code": String,                // language-code, e.g. "de" or "en"
    "native_name": String,
    "country_flag_url": String,    // url to flag-image
    "dir": String                  // reading direction {"ltr"|"rtl"}
  },
  ...
]

Pages/Events/Locations/Disclaimer

REQUEST

Get all pages/events/locations/disclaimer

GET /{site}/{language}/wp-json/extensions/v3/{pages|events|locations|disclaimer} HTTP/1.1
Host: web.integreat-app.de

RESPONSE

[
  {
    "id": Number,
    "url": String,             // url to post
    "path": String,            // path to post (url without host)
    "title": String,
    "modified_gmt": String,    // date and time of the last modification ("YYYY-MM-DD HH:MM:SS")
    "excerpt": String,         // post summary (usually the first paragraph of the content without html tags)
    "content": String,
    "parent": {
      "id": Number,            // id of parent post
      "url": String            // URL of parent post
    },
    "order": Number,
    "available_languages": {
      String: {                // language code of available language
        "id": Number,          // id of translated post
        "url": String          // url of translated post
      },
      ...
    },
    "thumbnail": String,
    "event": {                        // only present on event-endpoint
      "id": Number,
      "start_date": String,           // YYYY-MM-DD
      "end_date": String,             // YYYY-MM-DD
      "all_day": Boolean,
      "start_time": String,           // HH:MM:SS local time
      "end_time": String,             // HH:MM:SS local time
      "recurrence_id": Number|null
    },
    "location": {                     // only present on event- or location-endpoint
      "id": Number|null,
      "name": String|null,
      "address": String|null,
      "town": String|null,
      "state": String|null,
      "postcode": String|null,
      "region": String|null,
      "country": String|null,
      "latitude": String|null,
      "longitude": String|null
    },
    "hash": String             // MD5-hash of post
  },
  ...
]

Note: The disclaimer-endpoint will only return one post, not a list of posts.

REQUEST

Get only pages/events/disclaimer, which have been modified (includes created) or deleted (send the ids/paths and hashes of all local pages as json). Either ids or paths are required, but cannot be mixed in the same request.

POST /{site}/{language}/wp-json/extensions/v3/{pages|events|disclaimer} HTTP/1.1
Host: web.integreat-app.de
Content-Type: application/json

[
  {
    "id": Number | "path": String,
    "hash": String
  },
  ...
]

RESPONSE

{
  "deleted": [
    {
      "id": Number | "path": String
    },
    ...
  ],
  "changed": [
    {
    ... (see GET-request above for details to the parameters of a post)
    },
    ...
  ]
}

Single Post

REQUEST

Get a single post by id or url (only one of both parameters is required)

GET /{site}/{language}/wp-json/extensions/v3/post?id={id}&url={url} HTTP/1.1
Host: web.integreat-app.de

RESPONSE

{
    ... (see request above for details to the parameters of a post)
}

Children of a Post

REQUEST

Get all (direct) children of a post by id or url (only one of both parameters is required)

GET /{site}/{language}/wp-json/extensions/v3/children?id={id}&url={url} HTTP/1.1
Host: web.integreat-app.de

RESPONSE

[
  {
    ... (see request above for details to the parameters of a post)
  },
  ...
]

Parents of a Post

REQUEST

Get all (up to the root-page) parents of a post by id or url (only one of both parameters is required)

GET /{site}/{language}/wp-json/extensions/v3/parents?id={id}&url={url} HTTP/1.1
Host: web.integreat-app.de

RESPONSE

[
  {
    ... (see request above for details to the parameters of a post)
  },
  ...
]

Extras

Get all enabled extras for a specific location

REQUEST

GET /{site}/{language}/wp-json/extensions/v3/extras HTTP/1.1
Host: web.integreat-app.de

RESPONSE

[
  {
    "name": String,         // name of extra
    "alias": String,        // alias of extra
    "url": String,          // url to extra
    "post": {               // post-data (key & value pairs) for url (if needed) as json-object
      String: String,
      ...
    }|null,
    "thumbnail": String,    // url of thumbnail
  },
  ...
]

Feedback

Page/Event/Disclaimer

Feedback about a single page, event or disclaimer

REQUEST

POST /{site}/{language}/wp-json/extensions/v3/feedback HTTP/1.1
Host: web.integreat-app.de
Content-Type: application/json

[
  {
    "id": Number|null,             // if of the page/event (either id or url is required)
    "permalink": String|null,      // permalink of the page/event (either id or url is required)
    "comment": String,             // your message (either comment or rating is required)
    "rating": 'up'|'down'|null,    // up- or downvote (either comment or rating is required)
    "category": String|null,       // comment category (e.g. "Inhalte" or "Technisches Feedback")
  },
  ...
]

Extra

Feedback to a specific extra

REQUEST

POST /{site}/{language}/wp-json/extensions/v3/feedback/extra HTTP/1.1
Host: web.integreat-app.de
Content-Type: application/json

[
  {
    "alias": String,               // alias of the extra you want to comment on (required)
    "comment": String,             // your message (either comment or rating is required)
    "rating": 'up'|'down'|null,    // up- or downvote (either comment or rating is required)
    "category": String|null,       // comment category (e.g. "Inhalte" or "Technisches Feedback")
  },
  ...
]

Search

Feedback about a search result

REQUEST

POST /{site}/{language}/wp-json/extensions/v3/feedback/search HTTP/1.1
Host: web.integreat-app.de
Content-Type: application/json

[
  {
    "query": String,               // query string of the search you want to comment on (required)
    "comment": String,             // your message (either comment or rating is required)
    "rating": 'up'|'down'|null,    // up- or downvote (either comment or rating is required)
    "category": String|null,       // comment category (e.g. "Inhalte" or "Technisches Feedback")
  },
  ...
]

Cities

Feedback to all available cities / about the city-list

REQUEST

POST /{site}/{language}/wp-json/extensions/v3/feedback/cities HTTP/1.1
Host: web.integreat-app.de
Content-Type: application/json

[
  {
    "comment": String,             // your message (either comment or rating is required)
    "rating": 'up'|'down'|null,    // up- or downvote (either comment or rating is required)
    "category": String|null,       // comment category (e.g. "Inhalte" or "Technisches Feedback")
  },
  ...
]

Categories

Feedback to the main categories of a city, e.g. which category is missing

REQUEST

POST /{site}/{language}/wp-json/extensions/v3/feedback/categories HTTP/1.1
Host: web.integreat-app.de
Content-Type: application/json

[
  {
    "comment": String,             // your message (either comment or rating is required)
    "rating": 'up'|'down'|null,    // up- or downvote (either comment or rating is required)
    "category": String|null,       // comment category (e.g. "Inhalte" or "Technisches Feedback")
  },
  ...
]

Extras

Feedback to all available extras, e.g. which extra is missing

REQUEST

POST /{site}/{language}/wp-json/extensions/v3/feedback/extras HTTP/1.1
Host: web.integreat-app.de
Content-Type: application/json

[
  {
    "comment": String,             // your message (either comment or rating is required)
    "rating": 'up'|'down'|null,    // up- or downvote (either comment or rating is required)
    "category": String|null,       // comment category (e.g. "Inhalte" or "Technisches Feedback")
  },
  ...
]

Events

Feedback to all available events, e.g. which type of events are missing

REQUEST

POST /{site}/{language}/wp-json/extensions/v3/feedback/events HTTP/1.1
Host: web.integreat-app.de
Content-Type: application/json

[
  {
    "comment": String,             // your message (either comment or rating is required)
    "rating": 'up'|'down'|null,    // up- or downvote (either comment or rating is required)
    "category": String|null,       // comment category (e.g. "Inhalte" or "Technisches Feedback")
  },
  ...
]

Firebase Messages

Retrieve messages that were sent with Google Firebase Cloud Messaging.

The topic for FCM messages is in the format /topics/{blog-id}-{language-code}-{channel}

Get messages (for channel)

Without the channel variable, messages for all channels will be included.

GET /{site}/{language}/wp-json/extensions/v3/fcm?channel={channel} HTTP/1.1
Host: web.integreat-app.de
Content-Type: application/json

[
  {
    "title": String,     // message title
    "message": String,   // message body
    "timestamp": String, // YYYY-MM-DD HH:MM:SS
    "channel": String    // channel name
  },
  ...
]

Push content

Push content into the Integreat CMS

Page

Request

POST /{site}/{language}/wp-json/extensions/v3/pushpage HTTP/1.1
Host: web.integreat-app.de
Content-Type: application/json

{
  "page_id": Integer,
  "content": String,
  "token": String
}

Response

{
  "status": String //"success", "error", "denied"
}

Test API with WebApp

To use any API URL with the WebApp, use the following JavaScript console command: window.localStorage.setItem('api-url', 'your test api url')