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"
}

Pagination

Most queries which return multiple records will return records in batches of 10. This can be customised by passing "?limit=x" to the end of the query, where x is the number of records to return.

Paginated records will be provided with "from" and "max" cursors - which indicate the key value on the first and final record on the page. This is usually the ID number, but for records where IDs will not be sequential (notably articles), another field may be used instead. For articles, the ID number of the entry in the publication table for the article will be provided instead, which will be sequential.

The cursors can be used in 3 ways:

  • To refresh the current page (for example, if the limit is increased and you wish to keep the same start point), pass "?after=x" where x is the value of the "from" cursor less 1.
  • To obtain the next page, pass "?after=x" where x is the value of the "max" cursor.
  • To obtain the previous page, pass "?before=x" where ix the value of the "from cursor".

The before/after parameters operate a sample less than/greater than test in the database query. As a result, to refresh the current page you will need to deduct an amount (1 is fine) from the "from" cursor otherwise the first result on the current page may disappear. Alternatively, you can reuse the cursor values from the previous query you made, or just re-run the query if you are refreshing the first page.

If you follow a cursor beyond the range of available results, a 404 response will be provided.


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
comment_count Number of comments on article Int
img_caption Caption for the image String

Previously, an array of comments was included in this object. To obtain comments, please now use the Article Comments endpoint.

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, nor can any comments allocated to it 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 ID of comment this is a reply to OR null Int
numReplies Number of replies this comment has Int
likes Number of likes Int
dislikes Number of dislikes Int

numReplies only includes comments which are accessible, i.e. those which have not been moderated out, and those where the user's email address has been validated.

Example object

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

Remarks

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

If the comment requested is for an article is in a "secret" section, it cannot be accessed.


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 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 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]

Specific Comment

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

Returns a specific comment object.

The comment will only be returned if all of the following conditions are met:

  • The article the comment relates to has been published
  • The comment, and that of all the parents of this comment back to the root comment, has not been moderated out
  • The email address the comment, and that of all the parents of this comment back to the root comment, is posted against has been validated

Example call

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

Example response

[comment_object]

Comments by Article

http://api.felixonline.co.uk/comments/article/:article_id

Returns comments on an article.

The comments will only be returned if all of the following conditions are met:

  • The article the comment relates to has been published
  • The comment has not been moderated out
  • The email address the comment is posted against has been validated

Only root comments (i.e. those which are not replies of another) are returned, and comments are provided in date descending order.

Example call

http://api.felixonline.co.uk/comments/article/1234

Example response

[
    [comment_object],
    [comment_object],
    [comment_object],
    [comment_object],
    [comment_object],
    [comment_object],
    [comment_object],
    [comment_object],
    [comment_object],
    [comment_object]
]

Replies for Comment

http://api.felixonline.co.uk/comments/replies/:parent_id

Returns replies to a comment.

The replies will only be returned if all of the following conditions are met:

  • The article the parent comment relates to has been published
  • The parent comment, the child comment, and that of all the parents of this comment back to the root comment, has not been moderated out
  • The email address the comment, the child comment, and that of all the parents of this comment back to the root comment, is posted against has been validated

If a child comment fails any of the above tests, but the parent comment (and all of its parents back to the root comment) passes, then just the offending child commit will be omitted.

Only the first tier of comments (i.e. those which are not a child of a child of the parent comment) are returned, and comments are provided in date ascending order. Note that this is the reverse order to that of article comments.

Example call

http://api.felixonline.co.uk/comments/replies/1234

Example response

[
    [comment_object],
    [comment_object],
    [comment_object],
    [comment_object],
    [comment_object],
    [comment_object],
    [comment_object],
    [comment_object],
    [comment_object],
    [comment_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],
    ...
]

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],
    ...
]

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,
    ...
]

Archive Issue by 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
]

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,
    ...
]

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,
    ...
]

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,
    ...
]

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,
    ...
]

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

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]
]

Record Update Timestamps

http://api.felixonline.co.uk/record_versioning/:table/:key

Returns either the date of the last update/creation, or the date the record specified is deleted.

Returns 404 if no entries are found in the event log for this record. Where a database was in use prior to January 2016, many records will not have entries in the event log as they would have been created before the event log existed. Subsequent updates to these records will create new events.

The date is provided as a POSIX timestamp

Please check the latest database schema for table names, however for convenience the most common ones are:

  • article
  • user
  • image

Example call

http://api.felixonline.co.uk/record_versioning/article/5

Example response

{
    "deleted": 0,
    "date": 123456,
    "user": "felix"
}

Alternative query for articles

http://api.felixonline.co.uk/record_versioning/article/:id/text

Article text is stored in a separate schema to the rest of the article data to mitigate historic MySQL performance deterioration when selecting records which contain very large TEXT fields. Therefore, to obtain the update date of an article's text, either the text ID must be identified and a record_versioning query run against the text_story table.

As an alternative, you may call this query, providing the ID number of the article you wish to check the text for. The API will automatically identify the text ID for you and run the relevant query.

Note that updating an article text is not guaranteed to cause an update on the article record itself.

An attempt to run this query (by appending "/text") on a table other than article will result in a 404 error.


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.