NewsLynx: measuring the qualitative and quantitative impact of your journalism¶

Required Settings¶

config.yaml contains all the information we need to run NewsLynx. As you’ll see below, the App also utilizes this file for it’s configurations.

In this file, we require, at, minimum, the following fields:

• super_user:

  • The name of the Super User for this NewsLynx install. / org settings.

• super_user_email:

  • The Super User’s email (what you use to login with).

• super_user_password:

  • The Super User’s login password. This password will enable login to all other user profiles.

• super_user_apikey:

  • The Super User’s apikey. Principally here for development ease. Enables the regeneration of the datbase without resetting credentials.

• api_dns:

  • The URL of the final app. This is used when you authenticate with services to redirect you back to where you came from. This field isn’t required if you aren’t using the app at all.

API credentials¶

This file is also where you configure your credentials for Google Analytics, Twitter, Facebook, and other services. These aren’t credentials for the news organization(s), rather, your instance of NewsLynx needs an “app” with each of these services that each news organization gives its tokens to. For example, it’s the app that you will see in your Google account under apps that have access to the news organization’s account tokens. You can give that application the NewsLynx logo if you like, which will be presented to users when they authenticate with these different services from within the NewsLynx interface.

• twitter_api_key:

  • See Twitter’s developer docs for for details on how to create an application on Twitter and configure these credentials. The option you want is to create an app. Set the callback url to http://<app-url>/settings. If you’re running it on a port other than 80, put that in the url.

• twitter_api_secret:

  • See Twitter’s developer docs for for details on how to create an application with Twitter and configure these credentials.

• google_analytics_client_id:

  • See Google’s developer docs for for details on how to create an application with Google Analytics and configure these credentials. You’ll want to create an application and enable the Analytics API. Then click on “Credentials” on the left and create an oAuth 2.0 for a “web application.” Set the callback URI to http://<api-url>:5000/api/v1/auths/google-analytics/callback

• google_analytics_client_secret:

  • See Google’s developer docs for for details on how to create an application with Google Analytics and configure these credentials. You’ll want to create an application and enable the Analytics API. Then click on “Credentials” on the left and create an oAuth 2.0 for a “web application.” Set the callback URI to http://<api-url>:5000/api/v1/auths/google-analytics/callback.

• facebook_app_id:

  • See Facebook’s developer docs for for details on how to create an application on facebook and configure these credentials.

• facebook_app_secret:

  • See Facebook’s developer docs for for details on how to create an application on facebook and configure these credentials.

• reddit_user_agent:

  • A reddit-friendly User Agent.

• embedly_api_key:

  • An API key for using Embedly for content extraction. If not provided, we fall back on internal methods.

Default Tags and Recipes¶

In addition to these settings, you can also configure a list of default Tags and Recipes to create for every new Organization. This is useful for creating applications on top of the API which onboard new Organizations and Users without too much hassle.

These files live, by default, in ~/.newslynx/defaults. Each file should have the name of the items it contains and consist of a list of objects:

For example, ~/.newslynx/defaults/tags.yaml specifies a list of tags to apply to every new organization.

- name: Politics
  slug: politics
  color: '#a6cee3'
  type: subject

- name: Reprint / pickup
  slug: reprint-pickup
  category: citation
  level: media
  color: '#6699cc'
  type: impact

If you’d like to save these files elsewhere, you can modify the following configurations

• default_tags:

  • A path to a yaml file with a list of default Tags.
  • default = ~/.newslynx/defaults/tags.yaml

• default_recipes:

  • A path to a yaml file with a list of default Recipes.
  • default = ~/.newslynx/defaults/recipes.yaml

By default, NewsLynx Core installs the default Tags and Recipes needed to run the Application. If you’d like to install NewsLynx core without these defaults, make sure to use the --bare flat when you run newslynx init (more details on this below).

Additional Options¶

In addition, there are numerous optional configurations you can tweak to modify the performance of NewsLynx. You can also read through them in the source code.

Intialization¶

Once you have setup your configurations, follow the installation docs.

NewsLynx Core¶

NOTE - For most applications, we recommend following our automation guide. If you’d like to setup a development environment, following the instructions below for MacOS X. At this time, NewsLynx Core is not supported on Windows.

$ brew install postgresql --build-from-source --with-python

$ brew reinstall postgresql --build-from-source --with-python

$ brew install redis

$ redis-server

$ git clone https://github.com/newslynx/newslynx-core.git
$ cd newslynx-core
$ make app_install

$ git clone https://github.com/newslynx/newslynx-core.git
$ cd newslynx-core
$ make bare_install

NewsLynx App¶

NOTE - For most applications, we recommend following our automation guide. If you’d like to setup a development environment, following the instructions below for MacOS X.

Download the git repository and install dependencies:

$ git clone https://github.com/newslynx/newslynx-app && cd newslynx-app
$ npm install

NewsLynx Desktop¶

We also have a beta desktop version of NewsLynx App, which brings all of the same functionality of the web interface to a native environment, which can be easier for people to use. You can download the latest release for Mac OS X on the Releases page of the project repo.

Follow that project’s issue tracker for progress on the first 1.0 release. If you would like to try it in the mean time please do. If you would like a Windows or Linux version, let us know by filing an issue and we can bake one out.

Running Newslynx Core¶

Once you’ve installed and initialized NewsLynx Core, you can start a debug server with the following command:

$ newslynx debug

If you’d like to start a multi-theaded production server (some Sous Chefs may not work without this), run this command inside the root directory of newslynx-core:

$ bin/run

To start the task queue, run this command inside the root directory of newslynx-core:

$ bin/start_workers

To stop the task queue, run this command inside the root directory of newslynx-core:

$ bin/stop_workers

To start the Recipe scheduler, run this command:

$ newslynx cron

Running NewsLynx App¶

To start the server, in the newslynx-app folder, run the following:

$ npm start

This compiles your CSS and JS and runs the server with Forever.

When you see the following, it’s done and you can visit http://localhost:3000.

Note: If you are running this in production, you want to run it in behind https and tell the app you are doing so one of two ways:

1. Run it with the environment variable NEWSLYNX_ENV=https
2. Set https: true in your ~/.newslynx/config.yaml file

This will make sure your cookies are set securely.

#####################################
# HTTP listening on 0.0.0.0:3000... #
#####################################

$ npm run dev

$ npm run watch-files

$ npm run watch-server

Writing Sous Chefs¶

All Sous Chefs must inherit from the core newslynx.sc.SousChef class. You can see the source code for this class here. Every Sous Chef can define the following methods:

• setup

  • Configures the Sous Chef before executing it. This method can be used for authenticating wtih APIs or setting custom properties of the Sous Chef.

• run

  • Executes the Sous Chef. If this method is designed to bring data into NewsLynx, it should return a list or generator of dictionaries.

• load

  • Loads data output from run into NewsLynx. If this SousChef yields more than one record, it should utilize the Bulk API

• teardown

  • Do something after the Sous Chef finishes loading data.

You can see examples of our internal Sous Chefs here.

Configuration¶

All Sous Chefs are configured via a yaml or json file. These files follow a JSON schema which is defined here. Every Sous Chef consists of the following configurations:

• name

  • The display name of the Sous Chef.
  • Required

• slug

  • A unique slug for the Sous Chef. This can double as it’s ID in API calls. Must only contain letters and dashes. In regex, this means: '^[a-z][a-z\-]+[a-z]$'.
  • Required

• description

  • A description of what this Sous Chef does.
  • Required

• runs

  • The python import path for the Sous Chef. For instance, if you built a python module named my_sous_chef, this might take the value of my_sous_chef.SousChef. The class at the end of the import path must inherit from the core newslynx.sc.SousChef class. You can see the source code for this class here. You can see an example of one of these modules here or below.
  • Required

• creates

  • What type of collection does this Sous Chef create?
  • Required

  • Can be one of:

    • events
    • content
    • tags
    • metrics
    • report
    • external
    • internal

• option_order

  • The order in which options are rendered. This parameter should take a list of option names. This parameter primarily exists to aid in the dynamic rendering of Sous Chef input forms.
  • Optional

• includes

  • A list of relative paths to other Sous Chef config files to inherit for this Sous Chef. This prevents rewriting option definitions for Sous Chefs with similar behaviors. If this file contains a partial Sous Chef config, it’s filename should begin with an underscore. You can see an example of such a file here and it’s include statement here.
  • Optional

• requires_auths

  • A list of <endpoints-auths> names that must exist for an Organization before this Sous Chef can run.
  • Optional

• requires_settings

  • A list of <endpoints-settings> names that must exist for an Organization before this Sous Chef can run.
  • Optional

• options

  • The options this Sous Chef takes.
  • Optional (if this Sous Chef’s behavior should not be modified).

• metrics

  • The Metrics this Sous Chef creates.
  • Optional (unless the Sous Chef creates Metrics).

Options¶

Sous Chefs can specify as many options as they require. These options can be passed into the Sous Chef to change it’s behavior. At their core, Recipes are simply a populated list of these options. Each option follows the schema sepecified below:

• input_type

  • What type of input form should this option render?
  • This options enables newslynx-app to dynamically render forms to populate Sous Chef options.

  • This option can accept the following values

    • search

      • Render a search form to aid in populating the option’s value. In practice, this is used to add items to an option which can be searched for via the API.

    • radio

      • Render a radio form.

    • select

      • Render a drop-down form.

    • checkbox

      • Render a checkbox form.

    • checkbox-single

      • Render a single-checkbox. This would be used, for example, in the case that you want an non-required option to take a default value of true while enabling a user to override this default with a value of false.

    • number

      • Render a numeric form.

    • datepicker

      • Render a form which enables a user to select a date.

    • text

      • Render an open-ended text form.

    • paragraph

      • Render an open-ended text form with more room to fill in details. Primarily for use with description fields.

• input_options

  • If the input_type is radio, select, checkbox, or checkbox-single, a list of possible options to populate the form.
  • This parameter enables newslynx-app to dynamically render dropdowns, checkbox, or radio options.

• value_types

  • What value types does this option accept?
  • This parameter enables newslynx-core to exhaustively validate options before executing Sous Chefs.

  • This option can accept the following values:

    • datetime

      • An ISO-8601 date.

    • crontab

      • A cron string.

    • json

      • A complex option, usually a dictionary, which only needs to be json-serializable.

    • regex

      • Valid input to re.compile().

    • boolean

      • Truish (true, t, yes, y, 1, on) or Falsish Values (false, f, no, n, off).

    • numeric

      • Valid input to float() or int().

    • string

      • Valid input ot str()

    • nulltype

      • Any of (None, null, N/A, NaN)

    • url

      • A valid URL (determined by regular expresion.).

    • email

      • A valid email address (determined by regular expresion.)

    • searchstring

      • A custom type which we use to provide basic search capabilities to Sous Chefs (explained below.)

• accepts_list

  • Does this option accept a list of values?
  • Defaults to false.

• default

  • What is the default value for this options?
  • Defaults to null.

• required

  • Is this option required for the Sous Chef to properly run?
  • Defaults to false.

• help

  • Parameters to help users properly fill out options.
  • help is a dictionary of the following values:

  • placeholder

    • The placeholder/example text for this option.

  • link

    • A link for more details about this option.

  • description

    • A description of this option to display on form hover.

Default Options¶

All Sous Chefs come with the following default options. These exist for aiding in the creation and scheduling of Recipes. For more information on how these options affect when a Sous Chef is executed, refer to the Scheduling docs.

name:
    input_type: text
    value_types:
        - string
    required: true
    help:
        description: The name of the Recipe.

slug:
    input_type: text
    value_types:
        - string
    help:
        placeholder: (optional)
        description: The recipe slug. Lowercase and separated with '-'.

description:
    input_type: paragraph
    value_types:
        - string
        - nulltype
    help:
        placeholder: (optional)
        description: A description of what this recipe does.

schedule_by:
    input_type: select
    input_options:
        - minutes
        - time_of_day
        - crontab
        - unscheduled
    value_types:
        - string
        - nulltype
    default: null
    help:
        placeholder: minutes
        description: The method for scheduling the recipe.

crontab:
    input_type: text
    value_types:
        - crontab
        - nulltype
    default: null
    help:
        placeholder: "*/30 * * * *"
        description: A crontab string to use for scheduling this recipe.
        link: "https://en.wikipedia.org/wiki/Cron"

minutes:
    input_type: number
    value_types:
        - numeric
        - nulltype
    default: null
    help:
        placeholder: 60
        description: The frequency with which this Recipe should run (in minutes).

time_of_day:
    input_type: select
    input_options:
        - '12:00 AM'
        - '12:30 AM'
        ...
        - '11:30 PM'
    value_types:
        - string
        - nulltype
    default: null
    help:
        placeholder: '4:30 PM'
        description: The time of day at which this Recipe should run daily.

timeout:
    input_type: number
    value_types:
        - numeric
    default: 240
    help:
        placeholder: 240
        description: |
            The number of seconds after which this Recipe will time out.

Search¶

As mentioned above, Sous Chefs can accept options with a value type of searchstring. A search string is a built-in type that has the following capabilities (described through examples):

• term

  • match on a term

• ~term

  • fuzzy match on a term using jaro-winkler distance

• /.*term.*/

  • apply a regex

• "term1 term2"

  • match on a phrase

• ~"term1 term2"

  • fuzzy match on a phrase

• You can chain two search strings together with the following operators:

  • AND => must match both searchstrings
  • & => must match both searchstrings
  • OR => can match either term
  • | => can match either term

• There is not yet support of parenthetical grouping of chained terms.

Configuring Metrics¶

Sous Chefs which create metrics must also specify the schema of the metrics they create. This schema is specified in the Metrics docs.

Examples¶

The best way to understand how Sous Chef’s work is to look at the Source Code for the built-in modules here. You can see an example of a custom Sous Chef module here. If you’re interested in writing your own Sous Chefs, please refer to the writing-sous-chefs docs.

Options¶

All metrics have access to the following options:

• display_name

  • How should this metric be displated?

• description

  • An informative explanation of what this metric represents.

• type

  • Helps in determining how metric should be interpreted / summarized / presented.

  • Can be one of:

    • count

      • A number of something,
      • e.g. pageviews, time on page, attention minutes, etc.
      • count metrics are also fill-ins for Binary or Boolean fields. Simply store these values as 0 or 1. If you’d like to summarize them as Booleans, set the agg to max.
      • Metrics with this type will be assumed to have an agg of sum unless overridden.

    • cumulative

      • A count that increases over time.
      • This is a special type of Metric in that we should like to capture its differences over time periods. However, we also want to avoid alteration of the original source of the data. As a result, a cumulative metric is stored as cumulative sum, but when queried, is transformed into a count.
      • e.g. twitter shares, facebook comments, followers, etc.
      • Metrics with this type will be assumed to have an agg of sum unless overridden.

    • median

      • The median of a list of metrics.
      • e.g. median time on page.
      • Metrics with this type will be assumed to have an agg of median unless overridden.

    • average

      • The average of a list of metrics.
      • e.g. average time on page.
      • Metrics with this type will be assumed to have an agg of average unless overridden.

    • percentile

      • Usually a number beween 0 - 100.
      • e.g. percent internal traffic
      • Metrics with this type will be assumed to have an agg of avg unless overridden.

    • min_rank

      • A number which should be interpreted as “a lower number is good.”
      • e.g. position on homepage.
      • Metrics with this type will be assumed to have an agg of min unless overridden.

    • max_rank

      • A number which should be interpreted as “a higher number is good.”
      • e.g. position on homepage.
      • Metrics with this type will be assumed to have an agg of max unless overridden.

• agg

  • The function to use when aggregating this metric.
  • In practice, these map directly onto postgres functions.

  • Can be one of (for now):

    • sum
    • avg
    • median
    • max
    • min

• content_levels

  • This field lets us know that the metric is related to content items and should be stored at the specified level. For more on what this means see metrics-how-does-this-work

  • Can be one of:

    • timeseries

      • Accessible via the Content Timeseries API.

    • summary

      • Accessible via the Content Search API endpoints-content-items-search and when retrieving individual Content Items.

    • comparison

      • Accessible via endpoints-content-metrics-get-comparisons

• org_levels

  • This field lets us know that the metric is linked to an organization as a whole. For more on what this means see metrics-how-does-this-work

  • Can be one of:

    • timeseries

      • Accessible via endpoints-org-metrics-get-timeseries

    • summary

      • Accessible via endpoints-org-metrics-get-summary

For instance, the Sous Chef google-analytics-to-content-timeseries lists this metric configuration:

metrics:
    ga_pageviews:
        display_name: Pageviews
        description: |
            The number of times this page was opened,
            as reported by Google Analytics.
        type: count
        content_levels:
            - timeseries
            - summary
            - comparison
        org_levels:
            - timeseries
            - summary

    ga_total_time_on_page:
        display_name: Total Time on Page
        description: |
            The total time visitors spent on this page,
            as reported by Google Analytics.
        type: count
        content_levels:
            - timeseries
            - summary
            - comparison
        org_levels:
            - timeseries
            - summary

    ga_avg_time_on_page:
        display_name: Average Time on Page
        type: computed
        content_levels:
            - timeseries
            - summary
            - comparison
        org_levels:
            - timeseries
            - summary
        formula: '{ga_total_time_on_page} / NULLIF({ga_pageviews}, 0)'
        agg: avg

Tags¶

Authentication¶

Status Codes¶

{
  "status_code": 401,
  "error": "AuthError",
  "message": "Invalid API Key."
}

Namespacing¶

All endpoints are prefaced by /api/:version. The current (and only version) is v1.

Endpoints¶

All endpoints, unless ortherwise noted, return json. If you’d like to follow along with these examples, go ahead and set your apikey as an environment variable:

export NEWSLYNX_APIKEY='djljahflsdkfhasldkfhasldfa'
export NEWSLYNX_ORG=1 # The org id/slug you wish to access.
                      # Setting this will prevent you from having
                      # to repetitively pass this argument to the
                      # API client / command line interface.

{
  "organizations": [
    {
      "id": 1,
      "name": "Xosy Media",
      "timezone": "UTC"
    }
  ],
  "apikey": "djljahflsdkfhasldkfhasldfa",
  "name": "Merlynne Jones",
  "created": "2015-05-03T16:21:41.995821-04:00",
  "super_user": true,
  "admin": true,
  "id": 1,
  "email": "merlynne@newslynx.org"
}

{
  "email": "merylnne@newlsynx.org",
  "password": "a-secure-p4ssw0rd"
}

$ curl --data "email=merlynne@newslynx.org&password=a-secure-password" \
http://localhost:5000/api/v1/login

$ newslynx api me login email=merlynne@newslynx.org password=a-secure-password

from newslynx.client import API

api = API()
api.me.login(email=merlynne@newslynx.org, password=a-secure-password)

$ curl http://localhost:5000/api/v1/me\?apikey=$NEWSLYNX_APIKEY

$ newslynx api me get

from newslynx.client import API

api = API()
api.me.get()

{
  "email": "merylnne2@newlsynx.org",
  "old_password": "a-secure-p4ssw0rd",
  "new_password": "a-more-secure-p4ssw0rd",
  "name": "Meryl Jones"
}

$ curl -X PUT -d email=merlynne2@newslynx.org -d name="Meryl Jones" \
http://localhost:5000/api/v1/me\?apikey=$NEWSLYNX_APIKEY

$ newslynx api me update email=merlynne2@newslynx.org name="Meryl Jones"

from newslynx.client import API

api = API()
api.me.update(email="merlynne2@newslynx.org", name="Meryl Jones")

$ curl -X PUT -d old_password="a-secure-p4ssw0rd" -d new_password="a-more-secure-p4ssw0rd" \
http://localhost:5000/api/v1/me\?apikey=$NEWSLYNX_APIKEY

$ newslynx api me update old_password="a-secure-p4ssw0rd" new_password="a-more-secure-p4ssw0rd"

from newslynx.client import API

api = API()
api.me.update(
  old_password="a-secure-p4ssw0rd",
  new_password="a-more-secure-p4ssw0rd"
)

$ curl -X PUT http://localhost:5000/api/v1/me\?apikey=$NEWSLYNX_APIKEY\&refresh_apikey=true

$ newslynx api me update --refresh_apikey

from newslynx.client import API

api = API()
api.me.update(refresh_apikey=True)

$ curl -X DELETE http://localhost:5000/api/v1/me\?apikey=$NEWSLYNX_APIKEY

$ newslynx api me delete

from newslynx.client import API

api = API()
api.me.delete()

{
  "id": 1,
  "name": "liveqa",
  "timezone": "America/New_York"
  "users": [...],
  "settings": {...},
  "auths": {...}
}

$ curl http://localhost:5000/api/v1/orgs\?apikey=$NEWSLYNX_APIKEY

$ newslynx api orgs list

from newslynx.client import API

api = API()
api.orgs.list()

{
  "name": "ProPalpatine",
  "slug": "pro-palpatine",
  "timezone": "UTC"
}

$ curl --data "name=ProPalpatine&timezone=UTC&slug=pro-palpatine" \
http://localhost:5000/api/v1/orgs\?apikey=$NEWSLYNX_APIKEY

$ newslynx api orgs create name=ProPalpatine timezone=UTC slug=pro-palpatine

from newslynx.client import API

api = API()
api.orgs.create(name="ProPalpatine", timezone="UTC", slug="pro-palpatine")

$ curl http://localhost:5000/api/v1/orgs/1\?apikey=$NEWSLYNX_APIKEY

$ newslynx api orgs get id=1

from newslynx.client import API

api = API()
api.orgs.get(1)

{
  "name": "ProPalpatine2",
  "slug": "pro-palpatine-2",
  "timezone": "US/Western"
}

$ curl -X PUT -d name=ProPalpatine2 -d name=pro-palpatine-2 -d timezone=US/Western \
http://localhost:5000/api/v1/orgs/1\?apikey=$NEWSLYNX_APIKEY

$ newslynx api orgs update id=1 name=ProPalpatine2 timezone=US/Western slug=pro-palpatine-2

from newslynx.client import API

api = API()
api.orgs.update(1,
    name="ProPalpatine2",
    timezone="US/Western",
    slug="pro-palpatine-2")

$ curl -X DELETE http://localhost:5000/api/v1/orgs/1\?apikey=$NEWSLYNX_APIKEY

$ newslynx api orgs delete id=1

from newslynx.client import API

api = API()
api.orgs.delete(1)

$ curl http://localhost:5000/api/v1/orgs/1/users\?apikey=$NEWSLYNX_APIKEY

$ newslynx api orgs list-users id=1

from newslynx.client import API

api = API()
api.orgs.list_users(1)

{
  "name": "Brian Abelson",
  "email": "b@nytimes.cat",
  "password": "l0l4k4t",
  "admin": false
}

$ curl --data "name=Brian Abelson&email=b@nytimes.cat&password=l0l4k4t&admin=false" \
http://localhost:5000/api/v1/orgs/1/users\?apikey=$NEWSLYNX_APIKEY

$ newslynx api orgs create-user id=1 \
  name='Brian Abelson' email='b@nytimes.cat'\
  password='l0l4k4t' admin=false

from newslynx.client import API

api = API()
api.orgs.create_user(1,
    name='Brian Abelson', email=b@nytimes.cat,
    password=l0l4k4t, admin=false)

$ curl http://localhost:5000/api/v1/orgs/1/users/b@nytimes.cat\?apikey=$NEWSLYNX_APIKEY

$ newslynx api orgs get-user id=1 user_id=b@nytimes.cat

from newslynx.client import API

api = API()
api.orgs.get_user(1, 'b@nytimes.cat')

$ curl -X PUT http://localhost:5000/api/v1/orgs/1/users/m@nytimes.cat\?apikey=$NEWSLYNX_APIKEY

$ newslynx api orgs add-user id=1 user_id=b@nytimes.cat

from newslynx.client import API

api = API()
api.orgs.add_user(1, 'b@nytimes.cat')

$ curl -X DELETE http://localhost:5000/api/v1/orgs/1/users/m@nytimes.cat\?apikey=$NEWSLYNX_APIKEY

$ newslynx api orgs remove-user id=1 user_id=b@nytimes.cat

from newslynx.client import API

api = API()
api.orgs.remove_user(1, 'b@nytimes.cat')

{
    "id": 1,
    "name": "logo_image",
    "level": "orgs",
    "value": "http://example.com/mylogo.png",
    "json_value": false
}

{
    "id": 1,
    "name": "short_domains",
    "level": "orgs",
    "value": ["prplp.tn", "3mpi.re"],
    "json_value": true
}

$ curl http://localhost:5000/api/v1/orgs/settings\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api settings list

from newslynx.client import API

api = API()
api.settings.list()

$ curl --data "name=icon&value=http://example.com/mylogo.png" \
http://localhost:5000/api/v1/orgs/settings\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api settings create name=icon value=http://example.com/mylogo.png

from newslynx.client import API

api = API()
api.settings.create(name="icon" value="http://example.com/mylogo.png")

$ curl --data "name=short_urls&value=[\"prplt.in\"]&json_value=true" \
http://localhost:5000/api/v1/orgs/settings\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api settings create name=short_urls value='["prplt.in"]' json_value=true

from newslynx.client import API

api = API()
api.settings.create(name="short_urls", value=["prplt.in"], json_value=True)

$ curl http://localhost:5000/api/v1/orgs/settings/short_urls\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api settings get id=short_urls

from newslynx.client import API

api = API()
api.settings.get("short_urls")

$ curl -X PUT -d "value=[\"zzzz.in\"]" -d "json_value=true" \
http://localhost:5000/api/v1/orgs/settings/short_urls\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api settings update id=short_urls value='["zzzz.in"]' json_value=true

from newslynx.client import API

api = API()
api.settings.get("short_urls")

$ curl -X DELETE http://localhost:5000/api/v1/orgs/settings/short_urls\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api settings delete id=short_urls

from newslynx.client import API

api = API()
api.settings.delete("short_urls")

{
  id: 2,
  value: {
    "oauth_token_secret": "ldsfkasdlfjasdlfa380257234",
    "oauth_token": "2419585021-fdfdskadfjakjsdafjd"
  },
  name: "twitter"
}

$ curl http://localhost:5000/api/v1/auths\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api auths list

from newslynx.client import API

api = API()
api.settings.delete("short_urls")

$ curl http://localhost:5000/api/v1/auths/google-analytics\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api auths get service=google-analytics

from newslynx.client import API

api = API()
api.auths.get("google-analytics")

$ curl http://localhost:5000/api/v1/auths/google-analytics/grant\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api auths grant service=google-analytics

from newslynx.client import API

api = API()
api.auths.grant("google-analytics")

$ curl http://localhost:5000/api/v1/auths/google-analytics/revoke\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api auths revoke service=google-analytics

from newslynx.client import API

api = API()
api.auths.revoke("google-analytics")

$ curl http://localhost:5000/api/v1/auths/twitter\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api auths get service=twitter

from newslynx.client import API

api = API()
api.auths.get("twitter")

$ curl http://localhost:5000/api/v1/auths/twitter/grant\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api auths grant service=twitter

from newslynx.client import API

api = API()
api.auths.grant("twitter")

$ curl http://localhost:5000/api/v1/auths/twitter/revoke\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api auths revoke service=twitter

from newslynx.client import API

api = API()
api.auths.revoke("twitter")

$ curl http://localhost:5000/api/v1/auths/facebook\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api auths get service=facebook

from newslynx.client import API

api = API()
api.auths.get("facebook")

$ curl http://localhost:5000/api/v1/auths/facebook/grant\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api auths grant service=facebook

from newslynx.client import API

api = API()
api.auths.grant("facebook")

$ curl http://localhost:5000/api/v1/auths/facebook/revoke\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api auths revoke service=facebook

from newslynx.client import API

api = API()
api.auths.revoke("facebook")

{
    "id": 1,
    "org_id": 1,
    "name": "Politics",
    "slug": "politics",
    "type": "subject",
    "color": "#fc0"
}

{
    "id": 1,
    "org_id": 1,
    "name": "Social Media Share",
    "slug": "social-media-share",
    "type": "impact",
    "color": "#0cf",
    "category": "citation",
    "level": "media"
}

{
    "facets": {
        "levels": {
            "institution": 2,
            "media": 3,
            "individual": 1,
            "internal": 2,
            "community": 2
        },
        "categories": {
            "other": 5,
            "citation": 1,
            "change": 2,
            "achievement": 2
        },
        "types": {
            "impact": 10,
            "subject": 10
        }
    },
    "tags": [
        {
            "content_item_count": 10,
            "name": "Politics",
            "slug": "politics"
            "color": "#13962A",
            "org_id": 1,
            "type": "subject",
            "id": 14
        },
        {
            "category": "change",
            "name": "Legislative Change",
            "slug": "legislative-change",
            "level": "individual",
            "color": "#43E1D8",
            "event_count": 15,
            "org_id": 1,
            "type": "impact",
            "id": 1
        },
        ...
    ]
}

$ curl http://localhost:5000/api/v1/tags\?sort=-name\&type=subject\&apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api tags list sort=-name type=subject

from newslynx.client import API

api = API()
api.tags.list(sort='-name', type='subject')

$ curl --data "name=foo&type=subject&color=#fc0" \
http://localhost:5000/api/v1/tags\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api tags create name=foo type=subject color=#fc0

from newslynx.client import API

api = API()
api.tags.create(name='foo', type='subject' color='#fc0')

$ curl --data "name=bar&type=impact&color=#0cf&category=change&level=institution" \
http://localhost:5000/api/v1/tags\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api tags create name=bar type=impact color=#0cf category=change level=institution

from newslynx.client import API

api = API()
api.tags.create(name='bar', type='impact' color='#0cf', category='change', level='institution')

$ curl http://localhost:5000/api/v1/tags/1\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api tags get id=1

from newslynx.client import API

api = API()
api.tags.get(1)

$ curl -X PUT -d "color=#fc0aaa" \
  http://localhost:5000/api/v1/tags/21\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api tags update id=1 color=#fc0aaa

from newslynx.client import API

api = API()
api.tags.update(1, color='#fc0aaa')

$ curl -X DELETE http://localhost:5000/api/v1/tags/1\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api tags delete id=1

from newslynx.client import API

api = API()
api.tags.delete(1)

$ curl -X PUT http://localhost:5000/api/v1/tags/1/merge/2\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api tags merge from_id=1 to_id_2

from newslynx.client import API

api = API()
api.tags.merge(1, 2)

$ curl http://localhost:5000/api/v1/tags/categories

$ newslynx api tags categories

from newslynx.client import API

api = API()
api.tags.categories()

$ curl http://localhost:5000/api/v1/tags/levels

$ newslynx api tags levels

from newslynx.client import API

api = API()
api.tags.levels()

{
  "id": 3,
  "name": "Event from twitter user.",
  "slug": "twitter-user-to-event",
  "description": "Extracts events from a twitter user's timeline.",
  "runs": "newslynx.sc.events.twitter.User",
  "creates": "events",
  "is_command": false,
  "option_order": ["name", "slug", "decription", "screen_name", ...],
  "options": {
    "screen_name": {
      "required": true,
      "input_type": "text",
      "value_types": ["string"],
      "help": {
        "placeholder": "cspan"
      }
      ...
    }
  }
}

{
  "name": "Content Share Counts",
  "slug": "share-counts-to-content-metrics-timeseries"
  "description": "Computes a timeseries of share counts for an organization's content items.",
  "runs": "newslynx.sc.metrics.shares.TimeseriesCounts",
  "is_command": false,
  "creates": "metrics",
  "id": 6,
  "option_order": [],
  "options": {
    ...
    },
  "metrics": {
    "facebook_comments": {
      "display_name": "Facebook Comments",
      "type": "cumulative",
      "content_levels": ["timeseries", "summary", "comparison"],
      "org_levels": ["timeseries", "summary", "comparison"]
    },
    ...
  }
}

{
  "facets": {
    "creates": {
      "thing": 1,
      "event": 3
    },
    "runners": {
      "python": 4
    }
  },
  "sous_chefs": [
    ...
  ]
}

$ curl http://localhost:5000/api/v1/sous-chefs\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api sous-chefs list

from newslynx.client import API

api = API()
api.sous_chefs.list()

$ curl http://localhost:5000/api/v1/sous-chefs\?apikey=$NEWSLYNX_APIKEY\&org=1\&creates=events

$ newslynx api sous-chefs list creates=events

from newslynx.client import API

api = API()
api.sous_chefs.list(creates='events')

{
    "slug": "event-twitter-user-z",
    "name": "Event from twitter user 2",
    "runs": "newslynx.sc.events.twitter.User",
    "description": "Extracts events from a twitter user's timeline.",
    "creates": "events",
    "options": {
        "screen_name": {
          "required": true,
          "input_type": "text",
          "value_types": ["string"],
          "help": {
            "placeholder": "cspan"
          }
        }
    }
}

slug: twitter-user-to-event-b
name: Event from twitter user 2
runs: newslynx.sc.events.twitter.User
description: "Extracts events from a twitter user's timeline."
creates: events
options:
    screen_name:
      required: true
      input_type: text
      value_types:
        - string
      help:
        placeholder: cspan

$ curl -X POST \
     -H 'Content-Type:application/json' \
     --data-binary @sous-chef.json \
     http://localhost:5000/api/v1/sous-chefs\?apikey=$NEWSLYNX_APIKEY\&org=1

$ newslynx api sous-chefs create --data=sous-chef.yaml

import json

from newslynx.client import API


sc = json.load(open('sous-chef.json'))

api = API()
api.sous_chefs.create(**sc)

$ curl -X PUT -d http://localhost:5000/api/v1/sous-chefs/twitter-user-to-event\?apikey=$NEWSLYNX_APIKEY\&org=1