iaincollins / jess Goto Github PK

View Code? Open in Web Editor NEW

2.0 3.0 0.0 456 KB

Jess converts Postman API collections to JavaScript libraries

License: The Unlicense

JavaScript 92.99% CSS 7.01%

jess's Introduction

jess - a companion for postman

#About Jess

Jess converts Postman API collections to client libraries with documentation.

It's intended for use with Postman from http://www.getpostman.com

Jess parses the collection objects exposed by getpostman.com - including the markdown uses for comments and environment variables - and generates client libraries complete with inline documentation.

Currently it only generates JavaScript libraries (that leverage jQuery). The intention is to extend this over time to other languages, standalone documentation and demos.

You can find Jess running at http://getjess.com

Note: Jess is not associated with Postman.

#Hints and tips

##Collection, method and argument names

Jess automatically generates safe method and argument names from collections.

It works best with collections created with the latest version of Postman, but older versions are supported too.

##Method descriptions

The current version of Postman uses Markdown for comments, and this is what Jess expects (older versions allowed HTML, which is no longer supported).

Jess will display your comments in line above the method they are for, but it has special handling for lists - these are parsed for parameter descriptions but are not displayed as inline documentation.

###Adding descriptions for parameters

If you have a parameter called "argument_name" you can format a list with a description of the argument like this, and Jess will find it and use it to generate correctly formatted inline documentation.

* argument_name description of parameter

Note: All parameters in Postman are of type "string" - this is a limitation in Postman, which does not currently support specifying other types for parameters.

##Environment variables

If you are using environment variables in a collection be use to mark them up in the form {{variable}} (i.e. using double braces) which is what Postman expects.

For example, if your hostname and API Key options for your service are set using environment variables, use the following markup for your URLs and specify values for the "host" and "apiKey" environment variables in Postman:

{{host}}/api-path/method-name/?apiKey={{apiKey}}

If you this, Jess will recognise them as environment variables and create an "options" object where they can be specified. These values will then be used when invoking any methods that refernce these variables (along with any method specific arguments).

e.g.

yourLibrary.options.host = "http://api.example.com/api/";
yourLibrary.options.apiKey = "ABC123";
yourLibrary.yourMethod();

##Tweaking for performance

When generating JavaScript libraries jess currently generates methods that use asynchronous (blocking) rest calls so they can be easily consumed.

If you are creating your own library from a collection, you might wish to customise the library to use callbacks or event triggers instead.

Future versions of Jess may generate methods that support callbacks or event triggers by default.

jess's People

Contributors

Stargazers

Watchers

jess's Issues

All methods arguments should be unique

Some methods can end up with multiple arguments with the same name. Jess should check for this and prevent it (e.g. by appending a character to ensure uniqueness at least).

Example of a collection where this problem occurs:

11d570d56627036fcd55

Checkout jsonschema2pojo for ideas

jsonschema2pojo - which generates java classes from JSON and JSON schemas - is really interesting and gives me lots of ideas for Jess!

Extract variables from URLs and make them options

e.g. look for occurrences of strings like {{foo}} and {{bar}} and make them options declared at the top of the library.

this.options = { foo: "", bar: "" };

All the references to them should be converted to references to these properties.

Should use proper docblock markup in comments

e.g. @param before params in comments, @Version and @Date at the top of the library.

Provide option for generating standalone documentation

Provide option just to generate standalone, printable / online documentation.

Probably generating Markdown first, then adding options to convert that Markdown to HTML and PDF (as there are lots of libraries to handle that) might be a good idea.

If there is a desire to add interactive demos later, that might need to be done in native HTML + JS.

Remove dependency on jQuery

Add something like this to every library (will work with IE7+), instead of depending on jQuery:

function getURL(url, method, callback) {
    var xmlhttp = new XMLHttpRequest();
    xmlhttp.onreadystatechange = function() {
        if (xmlhttp.readyState == 4 && xmlhttp.status == 200)
            callback(xmlhttp.responseText);
    }
    xmlhttp.open(method, url, true);
    xmlhttp.send();
}

Provide options for generating libraries in other languages

Initially I'm thinking:

• JavaScript (client)
• JavaScript (nodejs)
• PHP
• Ruby

If anyone can provide an example of the demo in other popular languages (e.g. Python, Java) that would be really helpful.

Add option to specify callback

All functions should be able to take a callback as the last argument to allow for async calls, as sync calls (the current default behaviour) lock up most browser UIs while executing.

Change default query params format

To make methods arguments more manageable - particularly while bearing in mind making passing a function for callbacks easier - I'm pondering having methods take 2 arguments - the first an object (with all the parameters you wish to pass to the call) and a second being a function for the callback.

e.g. Usage example:

myLibrary.myMethod({ search: "Some text", date: "2014-04-01" }, function(response) {
// console.log(response);
});

Comments and feedback on this welcome.

Method that take single objects as an argument can cause problems

Example Collection ID's that doesn't quite generate correctly:
9daa87fe53b2453c4638
9e95b8130556209ed643

Provide option to generate framework for server side code

Would be nice to provide the option to generate a base project a for server side implementation of an API - e.g. in C#, Java, a script to generate a rails-api app in Ruby - from Postman collections.

This might be a useful option for people not using C# with .NET/Mono looking for an easier way to create web services (or even people using Java who want to make services that aren't SOAP/RPC).