API

This wiki specifies Metacademy's content API, which has the base URL: http://www.metacademy.org/api

Warning: this API is under active development and may change without notice

Content Server API

The API for the content server is currently read-only and responds to the following requests:

GET /dependencies gets a JSON representation of the dependency graph of the supplied concept(s) (specify via the concepts or ids parameter, see examples below)

GET /concepts/<concept_name> gets a JSON representation of <concept_name>

GET /search processes a search query (specified using the q parameter, see example below) and returns a list of JSON objects for the results

Examples

obtain the full dependency graph for gibbs sampling:

GET /dependencies?concepts=gibbs_sampling

obtain the full dependency graph for gibbs sampling and indian buffet process:

GET /dependencies?concepts=gibbs_sampling&concepts=indian_buffet_process

obtain the full dependency graph for gibbs sampling and indian buffet process using their permanent ids:

GET /dependencies?ids=n4mru8iv&ids=5638xo54

obtain a all data for gibbs sampling:

GET /concepts/gibbs_sampling

search query:

GET search?q=gibbs+sampling

JSON Response

Overview

The content API provides a JSON formatted response for all GET requests. The JSON format adheres to the following guiding principles:

• Underscores are used in place of spaces or hypens
• Dictionaries store data that can/should be uniquely referenced
• Ordered lists store data that are typically referenced as part of a group
• Ordered lists should only be used if it is possible that the data will have a multiplicity greater than one otherwise plain text is used
  • e.g. each concept node will only have one ID so an ordered list should not be used to specify the ID, while each node can have more than one dependency, so an ordered list should be used even if the given node only has one dependency.
• Empty strings, lists, or dictionaries are used to indicate the absence of data

Response Specification

{
    "nodes": {
        "node1_tag": {*node_content*},
        "node2_tag": {*node_content*},
        ...
    }, 
    "titles": {
        "tag1": "title for tag1",
        "tag2": "title for tag2",
        ...
    }
}

where the top level titles dictionary maps all present tags to titles (necessary because in/outlinks for the nodes do not include titles, only tags), and *node_content* is the following dictionary

{
    "title": "node_title",                  % plain text 
    "tag": "node_tag",                      % plain text (rarely changes for the given concept)
    "id": "node_id",                        % plain text (never changes for the given concept)
    "summary": "node_summary",              % plain text
    "pointers": [*ptr1*, *ptr2*, ...],      % ordered list of pointers (see below)
    "goals": [*goal1*, *goal2*, ...],       % ordered list of goals (see below)
    "questions": [*q1*, *q2*, ...]          % ordered list of questions (see below)
    "dependencies": [*dep1*, *dep2*, ...],  % ordered list of dependencies (see below)
    "resources": [*rsrc1*, *rsrc2*, ...],   % ordered list of resources (see below)
}

each pointer/goal/question in the ordered list "pointers"/"goals"/"questions" is the following dictionary

{
    "items": [*itm1*, *itm2*, ...]    % ordered list of processed text items (see below) that comprise 1 textile list item
    "depth": "integer"                % integer depth of list item
}

and each pointer/goals/question item is a dictionary with the following fields:

{
    "text": "text to display"        % plain text
    "link": "URL"                    % optional URL for text field
}

in the Metacademy application, these dictionaries are processed and then concatenated to form the displayed text

each dependency in "dependencies" is the following dictionary

{
    "from_tag": "node_id",            % plain text id of node
    "to_tag": "dep_node_id",          % plain text id of parent
    "reason": "reason_for_dep"        % plain text [or null if not available TODO should return empty string, not null]
}

and each resource in resources is the following dictionary

{
    "title": "resource_title",      % resource title
    "location": {*l1*, *l2*, ...},  % location items (see below)
    "resource_type": "rtype",       % text description of resource type, e.g. 'textbook'
    "free": 1,                      % boolean to indicate whether the resource is free access
    "core": 1,                      % boolean to indicate whether the resource is a core resource
    "level":"clevel",               % plain text, level of resource content, e.g. 'introductory'
    "edition": "str"                % edition number of resources
    "url": "http-url",              % URL of the resource
    "authors": ["a1", "a2"],        % list of authors of the given resource
    "dependencies": [dep1, dep2],   % list of dependencies for the given resource
    "extra": ["ec1", "ec2"]         % list of extra-info strings for the resource
    "note": ["n1", "n2"]            % list of notes for the given resource
}

location, free, and title are the required fields, and the location objects are the same pointer/goals/question items discussed above