Juga.io API 1.1

API Endpoint

https://api.juga.io/api/1.1

This API Blueprint documents Juga.io's public REST API.

If you are bootstrapping a project also take a look at Demo Project sources. It is a medium size nodejs example with many features and integrations (Feed reading, Categories, One Signal, Facebook Instant Articles RSS, etc.).

Feed ¶

A feed is a publishing channel.

Using juga.io, editors can create items and then schedule them for publishing into feeds.

Developers can read the feeds using this API and automatically embed the items inside websites, Facebook Instant Articles or App webviews. They can also automatically publish notifications on social networks. etc.

The common usage is to create one feed for each website you manage and then populate your website with the content of the feed.

If your website has a lot of traffic you may prefer to create one feed per section or language.

Read feed description ¶

Read feed description
GET`/feed/{feed_id}`

Returns a feed meta data.

URI Parameters

HideShow

feed_id: uuid (required) Example: UUID-Feed-Entry-ID
Unique feed identifier.

GET https://api.juga.io/api/1.1/feed/UUID-Feed-Entry-ID

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "UUID-Feed-ID",
  "lang": "en",
  "name": "Some feed",
  "description": "This feed is a great feed",
  "facebookPageId": "fb-page-id",
  "facebookPageName": "fb-page-name"
}

Response Attributes

id	string	(optional)
	id of the feed
lang	string	(optional)
	lang code of the feed
name	string	(optional)
	The name of the feed
description	string	(optional)
	Description of the feed
facebookPageId	string	(optional)
	The facebook page ID for this feed
facebookPageName	string	(optional)
	The facebook page name for this feed

Response Schema
HideShow

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "id of the feed"
    },
    "lang": {
      "type": "string",
      "description": "lang code of the feed"
    },
    "name": {
      "type": "string",
      "description": "The name of the feed"
    },
    "description": {
      "type": "string",
      "description": "Description of the feed"
    },
    "facebookPageId": {
      "type": "string",
      "description": "The facebook page ID for this feed"
    },
    "facebookPageName": {
      "type": "string",
      "description": "The facebook page name for this feed"
    }
  }
}

Read feed content ¶

Read feed content
GET`/feed/{feed_id}/entries?page={page}&limit={limit}&future={future}`

Returns a specific feed content.

Use this route to get the latest scheduled items.

URI Parameters

HideShow

feed_id: uuid (required) Example: UUID-Feed-ID
Unique feed identifier.
page: int (optional) Default: 0 Example: 2
Browsing page number.
limit: int (optional) Default: 100 Example: 100
Browsing entries per page.
future: boolean (optional) Default: false Example: false
Include future entries

GET https://api.juga.io/api/1.1/feed/UUID-Feed-ID/entries?page=2&limit=100&future=false

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "UUID-Feed-Entry-ID",
    "feedId": "UUID-Feed-ID",
    "itemId": "UUID-Item-ID",
    "date": 1517332163258,
    "kind": "Quiz",
    "title": "My item's title",
    "image": "http://example.com/item.jpg",
    "description": {
      "text": "# My markdown source",
      "html": "<h1>My markdown source</h1>"
    }
  }
]

Response Attributes

Array of:

enum

(required)

Choices:
- UUID-Feed-Entry-ID

id of the FeedEntry, unique identifier of item occurence inside a feed

feedId

enum

(required)

Choices:
- UUID-Feed-ID

feed id

itemId

enum

(required)

Choices:
- UUID-Item-ID

item id

date

enum

(required)

Choices:
- 1517332163258

publish date (ms since the epoch)

kind

enum

(required)

Choices:
- Article
- Quiz
- Test
- Calculator
- Slideshow
- HotOrNot
- OpenQuiz
- VersusWar
- Tournament
- Quiz

kind of the item

title

enum

(required)

Choices:
- My item's title

title of the item

image

enum

(optional)

Choices:
- http://example.com/item.jpg

meta image of the item

description

object

(required)

description of the item

text	enum	(required)	Choices: `# My markdown source`
	Markdown source text
html	enum	(required)	Choices: `<h1>My markdown source</h1>`
	Resulting HTML

custom

enum

(optional)

Choices:

a custom field you can use to pass meta data along juga.io's items

Response Schema
HideShow

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "enum": [
          "UUID-Feed-Entry-ID"
        ],
        "description": "id of the FeedEntry, unique identifier of item occurence inside a feed"
      },
      "feedId": {
        "type": "string",
        "enum": [
          "UUID-Feed-ID"
        ],
        "description": "feed id"
      },
      "itemId": {
        "type": "string",
        "enum": [
          "UUID-Item-ID"
        ],
        "description": "item id"
      },
      "date": {
        "type": "number",
        "enum": [
          1517332163258
        ],
        "description": "publish date (ms since the epoch)"
      },
      "kind": {
        "type": "string",
        "enum": [
          "Article",
          "Quiz",
          "Test",
          "Calculator",
          "Slideshow",
          "HotOrNot",
          "OpenQuiz",
          "VersusWar",
          "Tournament",
          "Quiz"
        ],
        "description": "kind of the item"
      },
      "title": {
        "type": "string",
        "enum": [
          "My item's title"
        ],
        "description": "title of the item"
      },
      "image": {
        "type": "string",
        "enum": [
          "http://example.com/item.jpg"
        ],
        "description": "meta image of the item"
      },
      "description": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "enum": [
              "# My markdown source"
            ],
            "description": "Markdown source text"
          },
          "html": {
            "type": "string",
            "enum": [
              "<h1>My markdown source</h1>"
            ],
            "description": "Resulting HTML"
          }
        },
        "required": [
          "text",
          "html"
        ],
        "additionalProperties": false,
        "description": "description of the item"
      },
      "custom": {
        "type": "string",
        "enum": [
          ""
        ],
        "description": "a custom field you can use to pass meta data along juga.io's items"
      }
    },
    "required": [
      "id",
      "feedId",
      "itemId",
      "date",
      "kind",
      "title",
      "description"
    ],
    "additionalProperties": false
  }
}

Read one feed entry ¶

Read one feed entry
GET`/feed/{feed_id}/entry/{entry_id}`

URI Parameters

HideShow

feed_id: uuid (required) Example: UUID-Feed-ID
Unique feed identifier.
entry_id: uuid (required) Example: UUID-Feed-Entry-ID
Unique feed entry identifier.

GET https://api.juga.io/api/1.1/feed/UUID-Feed-ID/entry/UUID-Feed-Entry-ID

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "UUID-Feed-Entry-ID",
  "feedId": "UUID-Feed-ID",
  "itemId": "UUID-Item-ID",
  "date": 1517332163258,
  "kind": "Quiz",
  "title": "My item's title",
  "image": "http://example.com/item.jpg",
  "description": {
    "text": "# My markdown source",
    "html": "<h1>My markdown source</h1>"
  }
}

Response Attributes

string

(optional)

id of the FeedEntry, unique identifier of item occurence inside a feed

feedId

string

(optional)

feed id

itemId

string

(optional)

item id

date

number

(optional)

publish date (ms since the epoch)

kind

enum

(optional)

Choices:
- Article
- Quiz
- Test
- Calculator
- Slideshow
- HotOrNot
- OpenQuiz
- VersusWar
- Tournament
- Quiz

kind of the item

title

string

(optional)

title of the item

image

string

(optional)

meta image of the item

description

object

(optional)

description of the item

text	string	(optional)
	Markdown source text
html	string	(optional)
	Resulting HTML

custom

string

(optional)

a custom field you can use to pass meta data along juga.io's items

Response Schema
HideShow

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "id of the FeedEntry, unique identifier of item occurence inside a feed"
    },
    "feedId": {
      "type": "string",
      "description": "feed id"
    },
    "itemId": {
      "type": "string",
      "description": "item id"
    },
    "date": {
      "type": "number",
      "description": "publish date (ms since the epoch)"
    },
    "kind": {
      "type": "string",
      "enum": [
        "Article",
        "Quiz",
        "Test",
        "Calculator",
        "Slideshow",
        "HotOrNot",
        "OpenQuiz",
        "VersusWar",
        "Tournament",
        "Quiz"
      ],
      "description": "kind of the item"
    },
    "title": {
      "type": "string",
      "description": "title of the item"
    },
    "image": {
      "type": "string",
      "description": "meta image of the item"
    },
    "description": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "description": "Markdown source text"
        },
        "html": {
          "type": "string",
          "description": "Resulting HTML"
        }
      },
      "description": "description of the item"
    },
    "custom": {
      "type": "string",
      "description": "a custom field you can use to pass meta data along juga.io's items"
    }
  }
}

Item ¶

Data ¶

Data
GET`/item/{item_id}`

URI Parameters

HideShow

item_id: uuid (required) Example: UUID-Item-ID
Unique item identifier.

GET https://api.juga.io/api/1.1/item/UUID-Item-ID

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "UUID-Item-ID",
  "lang": "en",
  "date": 1517332163258,
  "kind": "Quiz",
  "accountId": "UUID-Account-ID",
  "title": "My item's title",
  "image": "http://example.com/item.jpg",
  "description": {
    "text": "# My markdown source",
    "html": "<h1>My markdown source</h1>"
  },
  "data": ""
}

Response Attributes

string

(optional)

The item unique id

lang

string

(optional)

The lang code for this item

date

number

(optional)

Item last update date

kind

enum

(optional)

Choices:
- Article
- Quiz
- Test
- Calculator
- Slideshow
- HotOrNot
- OpenQuiz
- VersusWar
- Tournament
- Quiz

kind of the item

accountId

string

(optional)

Owner account unique id

title

string

(optional)

title of the item

image

string

(optional)

meta image of the item

description

object

(optional)

description of the item

text	string	(optional)
	Markdown source text
html	string	(optional)
	Resulting HTML

data

string

(optional)

item data, usually a json stringified

custom

string

(optional)

a custom field you can use to pass meta data along juga.io's items

Response Schema
HideShow

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The item unique id"
    },
    "lang": {
      "type": "string",
      "description": "The lang code for this item"
    },
    "date": {
      "type": "number",
      "description": "Item last update date"
    },
    "kind": {
      "type": "string",
      "enum": [
        "Article",
        "Quiz",
        "Test",
        "Calculator",
        "Slideshow",
        "HotOrNot",
        "OpenQuiz",
        "VersusWar",
        "Tournament",
        "Quiz"
      ],
      "description": "kind of the item"
    },
    "accountId": {
      "type": "string",
      "description": "Owner account unique id"
    },
    "title": {
      "type": "string",
      "description": "title of the item"
    },
    "image": {
      "type": "string",
      "description": "meta image of the item"
    },
    "description": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "description": "Markdown source text"
        },
        "html": {
          "type": "string",
          "description": "Resulting HTML"
        }
      },
      "description": "description of the item"
    },
    "data": {
      "type": "string",
      "description": "item data, usually a json stringified"
    },
    "custom": {
      "type": "string",
      "description": "a custom field you can use to pass meta data along juga.io's items"
    }
  }
}

Scores ¶

Scores
GET`/item/{item_id}/score`

Score API is used by Quiz and OpenQuiz contents.

For scalability reason juga.io is not offering a full ranking API but an approximative one using a segmented statistic table.

URI Parameters

HideShow

item_id: uuid (required) Example: UUID-Item-ID
Unique item identifier.

GET https://api.juga.io/api/1.1/item/UUID-Item-ID/score

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "UUID-Item-ID",
  "maxScore": 100,
  "plays": 999,
  "cumulatedScore": 10400,
  "segments": {
    "<segment_id>": 0
  }
}

Response Attributes

string

(optional)

Item id

maxScore

number

(optional)

Maximum score expected for this item

plays

number

(optional)

Number of plays (i.e.: number of saved scores)

cumulatedScore

number

(optional)

Sum of all saved scores

segments

object

(optional)

Keys are the score segment index as string, values are the number of registered scores falling in the segment.

<segment_id>	number	(optional)
	Keys are the score segment index as string, values are the number of registered scores falling in the segment.

Response Schema
HideShow

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Item id"
    },
    "maxScore": {
      "type": "number",
      "description": "Maximum score expected for this item"
    },
    "plays": {
      "type": "number",
      "description": "Number of plays (i.e.: number of saved scores)"
    },
    "cumulatedScore": {
      "type": "number",
      "description": "Sum of all saved scores"
    },
    "segments": {
      "type": "object",
      "properties": {
        "<segment_id>": {
          "type": "number",
          "description": "Keys are the score segment index as string, values are the number of registered scores falling in the segment."
        }
      },
      "description": "Keys are the score segment index as string, values are the number of registered scores falling in the segment."
    }
  }
}

Vote ¶

Vote
GET`/item/{item_id}/vote/export`

Some juga.io items support a vote kind of interaction (i.e.: Slideshow, HotOrNot, etc.).

You can programmatically access the results of user interaction using the following endpoints.

Returns a readable export of vote statistics.

Use this route to develop widgets and representations of users’ votes.

Ranking and scores are computed accordingly to the rules of the vote.

URI Parameters

HideShow

item_id: uuid (required) Example: UUID-Item-ID
Unique item identifier.

GET https://api.juga.io/api/1.1/item/UUID-Item-ID/vote/export

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "UUID-Item-ID",
  "isOpen": true,
  "rules": "note",
  "results": [
    {
      "id": 5,
      "pos": 0,
      "title": "Luke Skywalker",
      "image": "http://example.com/img.png",
      "note": 0.4,
      "score": 10,
      "votes": 88,
      "downs": 12
    }
  ]
}

Response Attributes

id	string	(optional)
	Item’s unique id.
isOpen	boolean	(optional)
	Vote is open to users
rules	enum	(optional)	Choices: `all` `one` `updown` `note` `note`
	Voting rules
results	array	(optional)
	Exported results

Response Schema
HideShow

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Item's unique id."
    },
    "isOpen": {
      "type": "boolean",
      "description": "Vote is open to users"
    },
    "rules": {
      "type": "string",
      "enum": [
        "all",
        "one",
        "updown",
        "note",
        "note"
      ],
      "description": "Voting rules"
    },
    "results": {
      "type": "array",
      "description": "Exported results"
    }
  }
}

Versus ¶

Versus
GET`/item/{item_id}/versus`

Versus API is used inside VersusWar and Tournament contents.

URI Parameters

HideShow

item_id: uuid (required) Example: UUID-Item-ID
Unique item identifier.

GET https://api.juga.io/api/1.1/item/UUID-Item-ID/versus

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "UUID-Item-ID",
  "isOpen": true,
  "stats": {
    "<candidateId>": {
      "id": 0,
      "fights": 10,
      "wins": 8
    }
  }
}

Response Attributes

string

(optional)

Item id

isOpen

boolean

(optional)

Versus is open to users

stats

object

(optional)

Versus statistics

<candidateId>

object

(optional)

id	number	(optional)
	Candidate id
fights	number	(optional)
	Number of fights
wins	number	(optional)
	Number of victories

Response Schema
HideShow

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Item id"
    },
    "isOpen": {
      "type": "boolean",
      "description": "Versus is open to users"
    },
    "stats": {
      "type": "object",
      "properties": {
        "<candidateId>": {
          "type": "object",
          "properties": {
            "id": {
              "type": "number",
              "description": "Candidate id"
            },
            "fights": {
              "type": "number",
              "description": "Number of fights"
            },
            "wins": {
              "type": "number",
              "description": "Number of victories"
            }
          }
        }
      },
      "description": "Versus statistics"
    }
  }
}

Embedding ¶

This section describes how you can display juga.io items inside your properties and how to customize them.

HTML embed

Our content can be embed right inside your HTML and customized using CSS.

To embed a juga.io item in your webpage you will need to:

Include some CSS in your <head>:

<link
  rel="stylesheet" style="text/css"
  href="https://cdn.juga.io/css/jugaio.css" />

Include your different items in your HTML.

Important: the ItemID-UUID must be replace by the ID of the item you want to embed. You will usually take it from the itemId field of feed entries.

<div class="juga-io" data-juga-io-item="ItemID-UUID"></div>

Include our javascript

<script src="https://cdn.juga.io/jugaio-client-deps.js"
        type="text/javascript"></script>
<script src="https://cdn.juga.io/jugaio.js"
        type="text/javascript"></script>

API Endpoint

Feed ¶

Read feed description ¶

Read feed descriptionGET/feed/{feed_id}

Headers

Body

Response Attributes

Response SchemaHideShow

Read feed content ¶

Read feed contentGET/feed/{feed_id}/entries?page={page}&limit={limit}&future={future}

Headers

Body

Response Attributes

Response SchemaHideShow

Read one feed entry ¶

Read one feed entryGET/feed/{feed_id}/entry/{entry_id}

Headers

Body

Response Attributes

Response SchemaHideShow

Item ¶

Data ¶

DataGET/item/{item_id}

Headers

Body

Response Attributes

Response SchemaHideShow

Scores ¶

ScoresGET/item/{item_id}/score

Headers

Body

Response Attributes

Response SchemaHideShow

Vote ¶

VoteGET/item/{item_id}/vote/export

Headers

Body

Response Attributes

Response SchemaHideShow

Versus ¶

VersusGET/item/{item_id}/versus

Headers

Body

Response Attributes

Response SchemaHideShow

Embedding ¶

HTML embed ¶

Read feed description
GET`/feed/{feed_id}`

Response Schema
HideShow

Read feed content
GET`/feed/{feed_id}/entries?page={page}&limit={limit}&future={future}`

Response Schema
HideShow

Read one feed entry
GET`/feed/{feed_id}/entry/{entry_id}`

Response Schema
HideShow

Data
GET`/item/{item_id}`

Response Schema
HideShow

Scores
GET`/item/{item_id}/score`

Response Schema
HideShow

Vote
GET`/item/{item_id}/vote/export`

Response Schema
HideShow

Versus
GET`/item/{item_id}/versus`

Response Schema
HideShow

HTML embed