Overview Contact

Welcome to the Felix Online API Documentation

Make yourself at home. If you have any questions then please do contact us.

This is the documentation for this API. It is a work in progress at the moment so please bear with us. Any features that are working will be clearly marked as such, as well as any that aren't!

Note: We only support JSON output format at the moment.

Errors

All API calls contain a field "error" which is 0 if the request was succesful, or 1 if it was not. If it is 1, a HTTP error status (at the moment, 404, 500, and 501 are supported) is sent, also stored in the field "error_code". A message explaining the error is found under "message". These two fields only show up for an "error" of 1. In the case of "error" being 0, the actual response is then contained in a field called "output".

Versioning

You can check what version of the API is running on the server by going to the endpoint "/version", this will report in the format of: { version: 0.2, name: "Name API", copyright: "(c) Name Corp" }


Values

Key Value Returns
id ID of article Int
title Full article title String
teaser Teaser text String
authors Array of user objects Array of User Objects
category Category object that article belongs to Category Object
date Article date (Unix timestamp) Int
published Timestamp of when article was published (Unix timestamp) Int
content Article content (html) String
raw_content Article content (json) as output by Sir Trevor String
image Article image object. Returns null if no image. Image Object
url Article url on Felix Online String
comments Array of comments on article Array of Comment Object
comment_count Number of comments on article Int
img_caption Caption for the image String

Raw Content

For advanced uses you may want to access this.

The content is built up of a number of components.

These components contain a type and then some data.

For text, heading, and list components, the text is stored in Markdown and roughly corresponds to one text component per paragraph.

Block quotes contain the text in Markdown, and an attribution under the cite parameter.

Videos have a source (e.g. YouTube) and a video ID number.

Images have a URI.

Finally, FelixImages contain an ID number for the image for fetching from the Image endpoint (see the Image Object), a caption, and an attribution. These should be used in preference to that obtained from the Image endpoint.

Example object

{
    id: "42",
    title: "Hello World",
    teaser: "Welcome to the Name API",
    category: [category_object],
    date: "1317387270",
    published: "1317362400",
    hidden: "0",
    hits: "101",
    authors: [
        [author_object],
        [author_object]
    ],
    content: "
        ....
    ",
    raw_content: "
        ....
    ",
    image: [image_object],
    url: "http://felixonline.local/news/42/hello-world/",
    img_caption: "A cat",
    "comment_count": 1,
    "comments": [
        [comment_object],
        ...
    ]
}

Remarks

Some sections are "secret" and can only be accessed from the Imperial College network.

If an article is in a "secret" section, it cannot be accessed.


Values

Key Value Returns
id ID of item Int
name Commenter name String
comment The comment String
timestamp Creation posix timestamp Int
reply Comment object this is a reply to OR null Comment object (this)
likes Number of likes Int
dislikes Number of dislikes Int

Example object

{
    "name":"Someone",
    "comment":"blah blah blah",
    "timestamp":1441648260,
    "reply":null,
    "likes":"0",
    "dislikes":"0",
    "id":"1234"
}

Values

Key Value Returns
id ID of image Int
title Title of image String
url Url of image (full size) String
name Filename of image String
description Image description String
timestamp Upload timestamp Int
attribution Attribution text String
attr_link Attribution link String
width Width of image Int
height Height of image Int

Example object

{
    id: "1376",
    title: "best interior.jpg",
    description: "",
    timestamp: "1317385179",
    attribution: "",
    attr_link: "",
    width: "1800",
    height: "1200",
    url: "http://img.felixonline.co.uk/upload/201109301319-felix-best-interior.jpg",
    name: "201109301319-felix-best-interior.jpg"
}

Values

Key Value Returns
user Username String
name Full Name String
info JSON encoded string of ldap user info String
description User description String
email Email address String
facebook Facebook profile url String
twitter Twitter handle (without @) String
websitename Website name String
websiteurl Website url String
img User image object (not used yet) Image Object

Example object

{
    user: "felix",
    name: "Felix",
    info: "",
    description: "The Felix account",
    email: "felix@imperial.ac.uk",
    facebook: "http://www.facebook.com/FelixImperial",
    twitter: "feliximperial",
    websitename: "Felix Online",
    websiteurl: "http://felixonline.co.uk",
    img: [image_object]
}

Values

Key Value Returns
id ID of section Int
label Main section title String
cat Short section title String
email Section contact email String
twitter Twitter handle (no @) String
secret If true, can only be accessed from the Imperial College network Boolean
editors Section Editors Array of User Objects
parent The parent section for this section [Section object]

Example object

{
    id: "42",
    label: "Hello",
    cat: "hello",
    email: "felix@imperial.ac.uk",
    twitter: "feliximperial",
    editors: [
        [user_object],
        [user_object]
    ],
    secret: false,
    parent: null
}

Remarks

Some sections are "secret" and can only be accessed from the Imperial College network.

However, marking a section as "secret" does not prevent access to child sections unless these are also "secret".


Values

Key Value Returns
id ID of item Int
article The article An Article Object
section Name of the front page section String
sort_order The order that the item shows Int

Example object

{
    id: "1376",
    section: "featured",
    sort_order: 0,
    article: [article_object]
}

Values

Key Value Returns
id ID of issue (not the same as issue number) Int
name Publication name String

Example object

{
    "id": 1,
    "name": "Felix"
}

Values

Key Value Returns
id ID of issue (not the same as issue number) Int
publication The publication A Publication Object
date Date of publication in POSIX timestamp Int
issue Issue number Int
url Link to issue page (pages are currently inactive) String
download-url Link to download the PDF String
thumbnail-url Link to a PNG of the thumbnail (size may vary)* String
thumbnail Original thumbnail filename* String
file-url File and folder of PDF in archive system* String
file Original file name* String

Items marked * are only shown in 'extended' outputs, see queries section. The 'simple' form of the object does not include the items with * by their description as this would significantly slow down the API.

Example object

{
    "issue": "1610",
    "date": 1434668400,
    "publication": [publication_object],
    "id": "1425",
    "url": "http:\/\/felix.local:8080\/issuearchive\/issue\/1425",
    "download-url": "http:\/\/felix.local:8080\/issuearchive\/issue\/1425\/download",
    "thumbnail-url": "http:\/\/felixonline.co.uk\/archive\/thumbs\/2015_1610_A.png",
    "thumbnail": "2015_1610_A.png",
    "file-url": "IC_2015\/2015_1610_A.pdf",
    "file": "2015_1610.pdf"
}

Articles

http://api.felixonline.co.uk/articles

Returns the 10 most recent articles published to Felix Online

Example response

[
    [article_object],
    [article_object],
    [article_object],
    [article_object],
    [article_object],
    [article_object],
    [article_object],
    [article_object],
    [article_object],
    [article_object]
]

Articles by Category

http://api.felixonline.co.uk/articles/:cat

Returns the 10 most recent articles published to a specific category

Example call

http://api.felixonline.co.uk/articles/news

Example response

[
    [article_object],
    [article_object],
    [article_object],
    [article_object],
    [article_object],
    [article_object],
    [article_object],
    [article_object],
    [article_object],
    [article_object]
]

Specific Article

http://api.felixonline.co.uk/articles/:id

Returns a specific article object

Example call

http://api.felixonline.co.uk/articles/1234

Example response

[article_object]

Sections

http://api.felixonline.co.uk/sections

Returns all sections

Example response

[
    [section_object],
    ...
]

Specific Section

http://api.felixonline.co.uk/sections/

Returns a section by ID number or cat value (see Section Objects)

Example response

[section_object]

Frontpage Articles

http://api.felixonline.co.uk/frontpage

Returns all articles in all front page sections. This only shows items pinned in places, some front page areas are dynamic based on recent uploads.

Example call

http://api.felixonline.co.uk/frontpage

Example response

[
    [frontpage_object],
    [frontpage_object],
    ...
]

Specific Frontpage Section Articles

http://api.felixonline.co.uk/frontpage/:section

Returns all articles in a front page section. The list of sections is not advertised but can be found through querying the front page end point directly.

Example call

http://api.felixonline.co.uk/frontpage/featured

Example response

[
    [frontpage_object],
    [frontpage_object],
    ...
]

Issue Archive Publication

http://api.felixonline.co.uk/archive

Returns all publications you can access issues for.

Example call

http://api.felixonline.co.uk/archive

Example response

[
    [publication_object],
    [publication_object],
    ...
]

Issue Archive Issues in Publication

http://api.felixonline.co.uk/archive/:pubid

Returns the simple issue object format for all issues in a publication. This can be quite slow if a publication has a lot of issues.

Example call

http://api.felixonline.co.uk/archive/1

Example response

[
    [issue_object] - simple,
    [issue_object] - simple,
    ...
]

Issue Archive Issue by Issue Number in Publication

http://api.felixonline.co.uk/archive/:pubid/:issueno

Returns a specific issue for a specific publication - supply the issue number NOT the issue ID

Example call

http://api.felixonline.co.uk/archive/1/1500

Example response

[
    [issue_object] - extended
]

Issue Archive Years

http://api.felixonline.co.uk/archive/years

Returns a list of years that issues exist in. Note that this is calculated by taking the first year that an issue exists, the last issue, and assumes an issue exists in every year in between so some years in the middle may have no issues.

Example call

http://api.felixonline.co.uk/archive/years

Example response

[
    int,
    int,
    int,
    ...
]

Issue Archive Years for Publication

http://api.felixonline.co.uk/archive/years/:pubid

Returns a list of years that issues for the specified publication exist in. Note that this is calculated by taking the first year that an issue exists, the last issue, and assumes an issue exists in every year in between so some years in the middle may have no issues.

Example call

http://api.felixonline.co.uk/archive/years/1

Example response

[
    int,
    int,
    int,
    ...
]

Issue Archive Issues in Year

http://api.felixonline.co.uk/archive/year/:year

Returns the simple issue object format for all issues in a year. This can be quite slow if a year has a lot of issues.

Example call

http://api.felixonline.co.uk/archive/year/2015

Example response

[
    [issue_object] - simple,
    [issue_object] - simple,
    ...
]

Issue Archive Issues in Year for Publication

http://api.felixonline.co.uk/archive/:pubid/year/:year

Returns the simple issue object format for all issues in a publication's year. This can be quite slow if a year has a lot of issues for that publication.

Example call

http://api.felixonline.co.uk/archive/1/year/2015

Example response

[
    [issue_object] - simple,
    [issue_object] - simple,
    ...
]

Issue Archive Latest Issues

http://api.felixonline.co.uk/archive/:pub/latest

Returns the extended form of the Issue object for the most recent issue in a publication.

Example call

http://api.felixonline.co.uk/archive/1/latest

Example response

[issue_object] - extended

Issue Archive Issue by ID

http://api.felixonline.co.uk/archive/issue/:id

Returns the extended form of the Issue object for the specified issue. The ID refers to the issue ID which may not be the same as the issue number.

Example call

http://api.felixonline.co.uk/archive/issue/1

Example response

[issue_object] - extended

Users

http://api.felixonline.co.uk/user/:login

Returns the user object for the specified username

Example response

[
    [user_object]
]

User's Articles

http://api.felixonline.co.uk/user/:login/articles

Returns the 10 most recent articles published to Felix Online by a user specified with their username

Example response

[
    [article_object],
    [article_object],
    [article_object],
    [article_object],
    [article_object],
    [article_object],
    [article_object],
    [article_object],
    [article_object],
    [article_object]
]

The API documentation is maintained by Philip Kent. You can file bug reports and feature requests online at: https://github.com/FelixOnline/API. Pull requests and contributions are always welcome.