Documentation

Create an importer
- Create your extension
- Code Snippets
  - Create a request
  - Create a group
  - Set a Basic Auth authentication
  - Set an OAuth 1 authentication
  - Set an OAuth 2 authentication
- Share your importer
- Use ES6 & webpack
- Use CoffeeScript & a Cakefile

Create an importer¶

Extensions
Create an importer

Paw can import third party files (e.g. from other HTTP clients, API description formats, HTTP archives, source files…) via importers. You can import via:

File ‣ Import ‣ File (⇧⌘I)

File ‣ Import ‣ Text (⌥⇧⌘I)

File ‣ Import ‣ URL (^⌥⇧⌘I)

Edit ‣ Paste and Import (⇧⌘V)

Drag & drop to Paw icon

Drag & drop to requests list

Create your extension¶

Choose an Extension Identifier

Choose an Extension Identifier¶

The Extension Identifier should be a reverse domain name and have a unique and meaningful name (e.g. com.mycompany.MyImporter).

Create files and folders

Create files and folders¶

Open the Extensions Directory: you can find it in the Preferences ‣ Extensions ‣ Open Extensions Directory.

Create a new folder and name it after your Extension Identifier.
Create a .js JavaScript file named after the last component of the identifier (e.g. MyImporter.js).
Additionally you can have a README file, or anything else.

Your file tree should look like:

Extensions/
- com.mycompany.MyImporter/
  MyImporter.js
  
  README.md

Structure the JavaScript file

Structure the JavaScript file¶

An Extension is represented as a JavaScript class.

Methods¶

Importers must have two methods:

import(context, items, options) Required: generates the output code
- context: a Context instance
- items: an array of items, each is a dictionary with the properties:
  content: the string
  
  url: the URL, if imported from URL
  
  file:
  
  name: file name, if imported from file
  
  path: file path, if imported from file
- options:
  inputs: the dictionary with all user inputs
  
  parent: the group in which the requests should be added (in case of a drag and drop into the request list), or null
  
  order: the order index in which the requests should be added (in case of a drag and drop into the request list)
canImport(context, items) Optional: evaluates items and returns a bool indicating if the extension can import the items; alternatively, can return the level of confidence as a float between 0.0 (can’t import) and 1.0 (can import for sure)
- context: a Context instance
- items: an array of string items

Static properties¶

Also, the class object have these properties:

identifier Required: the extension identifier
title Required: the extension display name
fileExtensions Optional: an array of file extensions (excluding the dot .) that the importer can handle
inputs Optional: the inputs the extension will have (if any)
help Optional: a URI pointing to the dynamic value documentation (if any)

Example¶

// Extensions are implemented as JavaScript classes
var MyImporter = function() {

    // implement the import() method to generate code
    this.import = function(context, items, options) {
        // Parse each string of `items`
        var desc += "\n";
        for (var i in items) {
            var item = items[i];
            desc += "  * " + item.content + "\n";
            if (/* parsing failed */) {
                // Failure
                throw new Error "Invalid input file";
            }
        }

        // Create requests (and groups)
        var request = context.createRequest('My Imported Request', 'POST', 'https://api.domain.com/path', 'This is a description of the imported request: ' + desc);

        // If file was dragged and dropped over the request list, insert request at proper location (group and order)
        if (options.parent !== undefined) {
            options.parent.insertChild(request, options.order);
        }

        // Success
        return true;
    }

    // check if we can import these items
    this.canImport = function(context, items) {
        var knownItems = 0;
        for (var i in items) {
            var item = items[i];
            var itemString = item.content;
            // analyze each string to determine if can import
            knownItems++;
        }
        var confidence = knownItems/(items.length);
        console.log("Confidence: " + confidence);
        return confidence;// or, true
    }
}

// set the Extension Identifier (must be same as the directory name)
MyImporter.identifier = "com.mycompany.MyImporter";

// give a display name to your Importer
MyImporter.title = "My Importer";

// supported file extensions
MyImporter.fileExtensions = ["index", "hya"];

// call to register function is required
registerImporter(MyImporter)

Define user inputs

Define user inputs¶

You can let the users of your Importer enter inputs that you’ll get the value during the import() call.

Learn how to add input fields to your extension.

Implement import()

Implement import()¶

Implement the import(context, items, options) method, parse items to add requests, groups or environments.

It gets:

context: a Context instance

items: an array of items, each is a dictionary with the properties:

content: the string

url: the URL, if imported from URL

file:

name: file name, if imported from file

path: file path, if imported from file

It returns:

boolean: if false it’s a failure

Promise: we wait on the Promise, passing two arguments to .then(resolve, reject)

Error: if an Error object is returned, it’s considered a failure, the Error.message is shown to the user

undefined (nothing returned): it’s considered a success

If an Error is thrown during the execution: it’s considered a JavaScript exception, the user is warned of the problem and the Error.message is displayed.

Also, all available classes and functions are in the Reference.

Here’s an example:

this.import = function(context, items, options) {
    // Parse strings like `POST http://api.domain.com/path`
    var i = 1;
    for (var i in items) {
        var item = items[i];
        var match = item.content.match(/^([a-z]+)\s+(.*)$/i);
        if (match == null) {
            // Failure
           throw new Error "Invalid input file";
        }

        // Create request
        var request = context.createRequest('Request ' + i, match[1], match[2]);

        i++;
    }

    // Success
    return true;
}

Code Snippets¶

Here are a few snippets on how to import items in Paw.

Create a request¶

var requestName = 'My Imported Request';
var requestMethod = 'POST';
var requestURL = 'http://api.domain.com/path';
var requestDescription = 'This is a POST request.';

// Create the request with name, HTTP method, URL and (optional) description
var request = context.createRequest(requestName, requestMethod, requestURL, requestDescription);

// Set headers
request.setHeader('Content-Type', 'text/plain');

// Set the body as raw text
request.body = 'Request Body...';

Create a group¶

// Create the request group giving its name
var group = context.createRequestGroup('My Group');

// Add request to group
var request = context.createRequest('My Request', 'GET', 'http://api.domain.com/path');
group.appendChild(request);

Set a Basic Auth authentication¶

var request = context.createRequest(requestName, requestMethod, requestURL);

// Set HTTP Basic Auth username and password
request.httpBasicAuth({
   'username':'USERNAME',
   'password':'PWD'
});

Set an OAuth 1 authentication¶

var request = context.createRequest(requestName, requestMethod, requestURL);

// Set OAuth 1 parameters
request.oauth1({
    'oauth_consumer_key':'_CONSUMER_KEY_',
    'oauth_consumer_secret':'_CONSUMER_SECRET_',
    'oauth_token':'_TOKEN_',
    'oauth_token_secret':'_TOKEN_SECRET_'

    // optional, default is a randomly generated nonce
    // 'oauth_nonce'

    // optional, default is the current timestamp
    // 'oauth_timestamp'

    // optional, default is empty
    // 'oauth_callback'

    // optional, either 'HMAC-SHA1' or 'PLAINTEXT', default is 'HMAC-SHA1'
    // 'oauth_signature_method'

    // optional, default is empty
    // 'oauth_additional_parameters'
});

Set an OAuth 2 authentication¶

var request = context.createRequest(requestName, requestMethod, requestURL);

// Set OAuth 2 parameters
request.oauth2({
    'client_id':'_CLIENT_ID_',
    'client_secret':'_CLIENT_SECRET_',
    'authorization_uri':'_AUTHORIZATION_URI_',
    'access_token_uri':'_ACCESS_TOKEN_URI_',
    'redirect_uri':'_REDIRECT_URI_'

    // optional, default is empty
    // 'scope'

    // optional, default is empty
    // 'state'

    // optional, default is 'Bearer '
    // 'token_prefix'

    // optional, default is empty, user can generate it via the GUI
    // 'token'
});

Use ES6 & webpack¶

See the cURL importer available on GitHub as an example of importer written in ES6, compiled with Babel, and using webpack as builder. It also have unit tests if you’re interested in making your extension rock solid!

Use CoffeeScript & a Cakefile¶

See the importer template available on GitHub to have a starting point for an importer written in CoffeeScript and uses a Cakefile for the build and install process.