API¶

API Objects
API Endpoints

The purpose of the API is to provide access to statistical summaries of the message database that can be used to render visualizations. With many of the API requests, a JSON object should be provided that indicates the user’s current interest and affects how the results will be delivered.

API Objects ¶

This module defines serializers for the main API data objects:

`DimensionSerializer`	JSON representation of Dimensions for the API.
`FilterSerializer`	Filters indicate a subset of the range of a specific dimension.
`MessageSerializer`	JSON representation of `Message` objects for the API.
`QuestionSerializer`	JSON representation of a `Question` object for the API.

class msgvis.apps.api.serializers.DimensionSerializer(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶

JSON representation of Dimensions for the API.

Dimension objects describe the variables that users can select to visualize the dataset. An example is below:

{
  "key": "time",
  "name": "Time",
  "description": "The time the message was sent",
}

class msgvis.apps.api.serializers.FilterSerializer(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶

Filters indicate a subset of the range of a specific dimension. Below is an array of three filter objects.

[{
  "dimension": "time",
  "min_time": "2010-02-25T00:23:53Z",
  "max_time": "2010-02-28T00:23:53Z"
},
{
  "dimension": "words",
  "levels": [
    "cat",
    "dog",
    "alligator"
  ]
},
{
  "dimension": "reply_count",
  "max": 100
}]

Although every filter has a dimension field, the specific properties vary depending on the type of the dimension and the kind of filter.

At this time, there are three types of filters:

Quantitative dimensions can be filtered using one or both of the min and max properties (inclusive).
The time dimension can be filtered using one or both of the min_time and max_time properties (inclusive).
Categorical dimensions can be filtered by specifying an include list. All other items are assumed to be excluded.

The ‘value’ field may also be used for exact matches.

class msgvis.apps.api.serializers.MessageSerializer(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶

JSON representation of Message objects for the API.

Messages are provided in a simple format that is useful for displaying examples:

{
  "id": 52,
  "dataset": 2,
  "text": "Some sort of thing or other",
  "sender": {
    "id": 2,
    "dataset": 1
    "original_id": 2568434,
    "username": "my_name",
    "full_name": "My Name"
  },
  "time": "2010-02-25T00:23:53Z"
}

Additional fields may be added later.

class msgvis.apps.api.serializers.QuestionSerializer(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶

JSON representation of a Question object for the API.

Research questions extracted from papers are given in the following format:

{
  "id": 5,
  "text": "What is your name?",
  "source": {
    "id": 13,
    "authors": "Thingummy & Bob",
    "link": "http://ijn.com/3453295",
    "title": "Names and such",
    "year": "2001",
    "venue": "International Journal of Names"
  },
  "dimensions": ["time", "author_name"]
}

The source object describes a research article reference where the question originated.

The dimensions list indicates which dimensions the research question is associated with.

API Endpoints ¶

The view classes below define the API endpoints.

Endpoint	Url	Purpose
`Get Data Table`	/api/table	Get table of counts based on dimensions/filters
`Get Example Messages`	/api/messages	Get example messages for slice of data
`Get Research Questions`	/api/questions	Get RQs related to dimensions/filters
Message Context	/api/context	Get context for a message
Snapshots	/api/snapshots	Save a visualization snapshot

class msgvis.apps.api.views.DataTableView(**kwargs)[source]¶

Get a table of message counts or other statistics based on the current dimensions and filters.

The request should post a JSON object containing a list of one or two dimension ids and a list of filters. A measure may also be specified in the request, but the default measure is message count.

The response will be a JSON object that mimics the request body, but with a new result field added. The result field includes a table, which will be a list of objects.

Each object in the table field represents a cell in a table or a dot (for scatterplot-type results). For every dimension in the dimensions list (from the request), the result object will include a property keyed to the name of the dimension and a value for that dimension. A value field provides the requested summary statistic.

The result field also includes a domains object, which defines the list of possible values within the selected data for each of the dimensions in the request.

This is the most general output format for results, but later we may switch to a more compact format.

Request: POST /api/table

Format: (request without result key)

{
  "dataset": 1,
  "dimensions": ["time"],
  "filters": [
    {
      "dimension": "time",
      "min_time": "2015-02-25T00:23:53Z",
      "max_time": "2015-02-28T00:23:53Z"
    }
  ],
  "result": {
    "table": [
      {
        "value": 35,
        "time": "2015-02-25T00:23:53Z"
      },
      {
        "value": 35,
        "time": "2015-02-26T00:23:53Z"
      },
      {
        "value": 35,
        "time": "2015-02-27T00:23:53Z"
      },
      {
        "value": 35,
        "time": "2015-02-28T00:23:53Z"
      },
      "domains": {
        "time": [
          "some_time_val",
          "some_time_val",
          "some_time_val",
          "some_time_val"
        ]
      ],
      "domain_labels": {}
}

class msgvis.apps.api.views.ExampleMessagesView(**kwargs)[source]¶

Get some example messages matching the current filters and a focus within the visualization.

Request: POST /api/messages

Format:: (request should not have messages key)

{
    "dataset": 1,
    "filters": [
        {
            "dimension": "time",
            "min_time": "2015-02-25T00:23:53Z",
            "max_time": "2015-02-28T00:23:53Z"
        }
    ],
    "focus": [
        {
            "dimension": "time",
            "value": "2015-02-28T00:23:53Z"
        }
    ],
    "messages": [
        {
            "id": 52,
            "dataset": 1,
            "text": "Some sort of thing or other",
            "sender": {
                "id": 2,
                "dataset": 1
                "original_id": 2568434,
                "username": "my_name",
                "full_name": "My Name"
            },
            "time": "2015-02-25T00:23:53Z"
        }
    ]
}

class msgvis.apps.api.views.KeywordMessagesView(**kwargs)[source]¶

Get some example messages matching the keyword.

Request: POST /api/search

Format:: (request should not have messages key)

{
    "dataset": 1,
    "keywords": "soup ladies,food,NOT job",
    "messages": [
        {
            "id": 52,
            "dataset": 1,
            "text": "Some sort of thing or other",
            "sender": {
                "id": 2,
                "dataset": 1
                "original_id": 2568434,
                "username": "my_name",
                "full_name": "My Name"
            },
            "time": "2015-02-25T00:23:53Z"
        }
    ]
}

class msgvis.apps.api.views.ActionHistoryView(**kwargs)[source]¶

Add a action history record.

Request: POST /api/history

Format:: (request should not have messages key)

{
   "records": [
       {
            "type": "click-legend",
            "contents": "group 10"
        },
        {
            "type": "group:delete",
            "contents": "{\"group\": 10}"
        }
    ]
}

class msgvis.apps.api.views.GroupView(**kwargs)[source]¶

Get some example messages matching the keyword.

Request: POST /api/group

Format:: (request should not have messages key)

{
    "dataset": 1,
    "keyword": "like",
    "messages": [
        {
            "id": 52,
            "dataset": 1,
            "text": "Some sort of thing or other",
            "sender": {
                "id": 2,
                "dataset": 1
                "original_id": 2568434,
                "username": "my_name",
                "full_name": "My Name"
            },
            "time": "2015-02-25T00:23:53Z"
        }
    ]
}

class msgvis.apps.api.views.KeywordView(**kwargs)[source]¶

Get top 10 keyword results.

Request: GET /api/keyword?dataset=1&q= [...]

{
    "dataset": 1,
    "q": "mudslide oso",
    "keywords": ["mudslide oso", "mudslide oso soup", "mudslide oso ladies"]
}

class msgvis.apps.api.views.ResearchQuestionsView(**kwargs)[source]¶

Get a list of research questions related to a selection of dimensions and filters.

Request: POST /api/questions

Format: (request without questions key)

{
    "dimensions": ["time", "hashtags"],
    "questions": [
        {
          "id": 5,
          "text": "What is your name?",
          "source": {
            "id": 13,
            "authors": "Thingummy & Bob",
            "link": "http://ijn.com/3453295",
            "title": "Names and such",
            "year": "2001",
            "venue": "International Journal of Names"
          },
          "dimensions": ["time", "author_name"]
        }
    ]
}

class msgvis.apps.api.views.DatasetView(**kwargs)[source]¶

Get details of a dataset

Request: GET /api/dataset/1

class msgvis.apps.api.views.APIRoot(**kwargs)[source]¶: The Text Visualization DRG Root API View.

API¶

API Objects¶

API Endpoints¶

API Objects ¶

API Endpoints ¶