api.webmaker.org

Webmaker services API.

Prerequisites

You will need to download and install:

• Nodejs >= v4.6.0
• postgreSQL >= v9.4
• redis >= v3.0

Installation

# Clone the repo
git clone https://github.com/mozilla/api.webmaker.org

# change into project directory
cd api.webmaker.org

# install dependencies using npm
npm install

# copy default environment config
cp env.sample .env

# create a database; -U and -W are only necessary if your pg instance needs authentication
createdb -U dbusername -W dbuserpassword webmaker

# create tables; -U and -W are only necessary if your pg instance needs authentication
psql -U dbusername -W dbuserpassword -d webmaker -f scripts/create-tables.sql

Note: this will set up an empty database

In order to quickly get up and running for development purposes, you will also want to create at least one user by logging into your postgresql instance:

$> psql -d webmaker -U dbusername

and then issuing the following user record creation instruction:

pg> insert into users (id, username, language) VALUES (1, 'testuser', 'en-US');

This will let you call any of the API endpoints with userid 1 without running into API errors due to missing users.

Migration

Migration scripts can be found in the migrations folder.

You can run all the scripts in order with npm run migrate or run each individually for a partial migration psql -U username -d dbname -f migrations/{migration_script}.sql

Run

Start the server with npm start

You can view documentation by navigating to http://localhost:2015/docs in your browser

Configuration

An important note for default PostgreSQL installations:

If you are using a vanilla PostgreSQL instance, you will either need to allow unauthenticated connections, or modify the POSTGRE_CONNECTION_STRING such that it is using the correct username and password, by using for following format instead of the one that is used in the sample.env file:

export POSTGRE_CONNECTION_STRING=postgresql://username:password@localhost:5432/webmaker

For default installations, this will have username postgres, with the password that you had to fill in during the PostgreSQL installation process.

The tests assume the user postgres exists and has no password set. They also assume that a database named webmaker_testing has been created, and that postgres has owner permissions. Create the database with createdb -U postgres webmaker_testing

Successfully working with New Relic

See the guide for configuring New Relic using environment variables to configure the New Relic agent

Optional Configuration

Test

The tests require access to a postgreSQL database named webmaker_testing. Create it by running the command createdb webmaker_testing, the test script will automatically create tables and populate them with data.

Run the tests with npm test

Migrations

Run database migrations with the following command npm run migrate -- webmaker

Substitute 'webmaker' in the last command with whichever database name your api is using. It will apply all migration scripts in the migrations file in order.

Bulk Action API

A bulk api endpoint exists to enable the client to execute many actions on the user's project, pages, elements in a single HTTP request instead of many individual ones.

• URL

  /user/{user}/bulk

• Method

  POST

• Authentication

  The Authorization header should contain a valid OAuth token provided by id.webmaker.org

  Authorization: token myoauth2tokenforwebmaker

• Body

  Post body should be valid JSON. It should contain a single attribute, actions, an array of at least one, and at most 1000 individual actions to execute in serial.

  Each action should contain three properties, type, method, and data. Type must be one of 'projects', 'pages', or 'elements'. Method must be one of 'create', 'update' or 'remove'. Data must contain attributes and values specific to the type and method of the action:

  • projects
  • create
    • title
    • String, required, up to 256 characters
    • thumbnail
    • Object, containing a key ("320") which is the URL of the thumnail.
  • update
    • id
    • Number, or string containing decimal digits, representing the unique id of a project
    • title
    • String, required, up to 256 characters
  • remove
    • id
    • Number, or string containing decimal digits, representing the unique id of a project
  • pages
  • create
    • projectId
    • Number, or string containing decimal digits, representing a project's unique id
    • x
    • Number, the x coordinate of the page
    • y
    • Number, the y coordinate of the page
    • styles
    • Optional object containing styles values for the page. defaults to {}
  • update
    • id
    • Number, or string containing decimal digits, representing the unique id of a page
    • x
    • Number, the x coordinate of the page
    • y
    • Number, the y coordinate of the page
    • styles
    • Optional object containing styles values for the page. defaults to {}
  • remove
    • id
    • Number, or string containing decimal digits, representing the unique id of a page
  • elements
  • create
    • pageId
    • Number, or string containing decimal digits, representing the unique id of a page
    • type
    • String, represents the element type
    • styles
    • Optional object containing styles values for the page. defaults to {}
    • attributes
    • Optional object containing attributes values for the page. defaults to {}
  • update
    • id
    • Number, or string containing decimal digits, representing the unique id of a element
    • styles
    • Optional object containing styles values for the page. defaults to {}
    • attributes
    • Optional object containing attributes values for the page. defaults to {}
  • remove
    • id
    • Number, or string containing decimal digits, representing the unique id of a element

  You can reference future id values using the following syntax: $1.id, where the number following the dollar sign represents the index of the action, and the path following it is used to grab the id you're looking for. For example:

  {
  "actions": [
    {
      "type": "projects",
      "method": "create",
      "data": {
        "title": "My Project"
      }
    },
    {
      "type": "pages",
      "method": "create",
      "data": {
        "projectId": "$0.id",
        "x": 0,
        "y": 0
      }
    }
  ]
  }

Diagrams

The Webmaker API uses id.webmaker.org to authenticate users and requests using Bearer tokens. Below is a sequence diagram describing how a create project request is handled for a first time user.