Flockler API v1 Documentation

The Flockler API provides programmatic access for you to consume all the content you have created with your Flockler Newsroom. With Flockler API you can continue creating content in Newsroom while being convinced that through Flockler API all your content is available whatever you need to do with it in the future. API content is divided in familiar sections and categories and is available in JSON.

This page will introduce you to the basic principles of the Flockler API and specific endpoint description pages will teach you more about the content that is available from this API.

The base endpoint for the API is https://api.flockler.com/v1/

Authentication

Our goal is to make your life as a developer as easy as possible, so we decided authentication is not required by default. This is a public API, you don't need any special keys or tokens to access your data.

If you want to hide your site, you can request API key from us (support). Enabling API key will disable API for your site unless the key is sent with every request

API key

Key should be used only between servers and not shown to enduser. Key must be included in every request as parameter or header. It is possible to limit access per IP address

Parameter: api_key

Example: https://...?api_key=kjh43k5wlfiugl0lsbk8ajnkwrkljls087jlhkdu8766h54j6fmggds9fgug5s7fsdj


Header: Authorization

Example: Authorization: FL-API-KEY kjh43k5wlfiugl0lsbk8ajnkwrkljls087jlhkdu8766h54j6fmggds9fgug5s7fsdj

Endpoints

Primary endpoints
These are the endpoints that you will be most likely using.

Articles

Sections

Feature endpoints
If you need to use one of the features listed here and your site does not have it yet, please contact Flockler support.

These are endpoints for features that aren't normally enabled for all sites.

Articles

Authors

Categories

Issues

Pages

Sites

Likes

Request

Parameters

Below are listed some of the more commonly used request parameters.


sideloading refactors the data and eliminates duplication. For example, if you requested for articles, you will get the articles' sections data in a separate block in the end of the response. Sideloading is true by default but you can switch to embedded mode by defining it to false

Example: ?sideloading=false


fields is useful when you know exactly what fields of the data you need. That decreases the payload of the response and makes it easier to handle when all the excessive stuff has been already cut off.

Example: ?fields=id,title,body,full_url


tag lets you to request only articles with a certain tag. Currently you can use only one tag per request.

Example: ?tag=marketing


count defines the number of items you get as a response. Count default for articles is 20 items per page but you can increase or decrease it as you like by defining the count-parameter in your request.

Example: ?count=40


max_id is for pagination. With max_id you can define the last processed item and request only items with a lower id (=older items). That way you can efficiently go through long lists of items and process them in smaller pieces.

Example: ?max_id=741275


since_id is for polling purposes. It defines the last id that has been processed and returns only items that have become available after that specific item. That way you can efficiently poll new items and exclude all the already processed ones from the responses.

Example: ?since_id=762681

Response

Currently Flockler API only responds via JSON. Most responses consist of a meta, pagination and data node. Sometimes you might also get some sideloadable data nodes. Below is an example of a typical response with the typical meta, pagination and data nodes:

{
  "meta": {
    "total_count": 214,
    "count": 20
  },
  "pagination": {
    "refresh": "https://api.flockler.com/v1/sites/609/sections/828/articles?since_id=239992",
    "base": "https://api.flockler.com/v1/sites/609/sections/828/articles?",
    "older": "https://api.flockler.com/v1/sites/609/sections/828/articles?max_id=239992"
  },
  "articles": []
}

Here we have a meta node, pagination node and lastly articles node, which in this case, is the data node.

Meta

total_count total number of available items.

count shows how many items are included in this response.

Pagination

base URL for fetching the basic resource.

refresh URL for fetching items that have been added after your last request. Good for polling for new items.

older URL for fetching next set of items (=older items). Is null when there are no more older items.

Data
The data is presented using an unique key for the request. If you requested for articles, the key will be called “articles”, if you requested a single article, the key will be called “article”. This is “the meat” of the response. It may be a list or dictionary, but either way this is where you'll find the data you requested.

Sideloading

Along with the actual data, you may receive some sideloadable data. For example, if you requested for articles, you will get the articles' sections data in a separate block in the end of the response.

Flockler API sideloads all the sections and authors by default. You may change the default with the "?sideloading=false" parameter.

Below is an example of a response with sideloadable author, category, and section data:

"articles": [
  {
    "article_url": "3-examples-of-brands-creating-content-on-a-budget",
    "author_ids": [
      1422
    ],
    "body": "<p><p>Some of the best examples of content ...",
    "section_id": 3908,
  }
],
"authors": [
  {
    "id": 1422,
    "job_title": "Designineer",
    "name": "AJ Hardwick"
  }
],
"categories": [
  {
    "category_url": "tutorial",
    "id": 357,
    "name": "Tutorial",
    "order_number": 1
  },
  {
    "category_url": "in-finnish",
    "id": 358,
    "name": "In Finnish",
    "order_number": 2
  }
],
"sections": [
  {
    "id": 3908,
    "name": "Blog",
  }
]

JSONP

You can use Flockler API also by JSONP. Callback can be declared with the callback-parameter.

https://api.flockler.com/v1/sites/609/articles?callback=flocklerApiCallbackFunction

HTTP Status Codes

200 OK Successful request.

400 Bad Request Most likely a missing or invalid parameter(s).

404 Not Found The requested item was not found.

500 Internal Server Error Something went wrong on our end.