Blueman

Convert an API Blueprint JSON file into a Postman collection.

Install Blueman as a Phar (recommended)

Use the installer to download Blueman:

$ curl -sS http://blueman.pixelfusion.co.nz/installer.php | php

This will grab the latest version of Blueman and copy it to your current directory. We recommend moving it to the bin directory so you can run the Blueman from anywhere:

$ mv blueman.phar /usr/local/bin/blueman

Whenever there is a new version of Blueman you can run self-update to update to the latest version:

$ blueman self-update

Install using Composer

Blueman can also be installed using Composer if you prefer that:

$ composer create-project pixelfusion/blueman your-project-name

Prerequisites

The API Blueprint JSON file that you want to convert with Blueman should be created using Drafter. By default Drafter creates refract formatted JSON files but Blueman only supports the AST format. You will have to force Drafter to use AST by passing the -t parameter, for example:

drafter -f json -t ast -o api.json api.md

Note: As of December 2015 the API Blueprint AST format has been deprecated. The API Blueprint AST has been superseded by API Description Refract Namespace. At this point Blueman only supports the AST format so as soon as Drafter drops support for generating AST formatted files, Blueman won't work anymore. Pull Requests to add support for the refract format are highly appreciated!

Usage

To generate a Postman collection you run the convert command. For example, if the API Blueprint JSON file you generated is called api.json you would execute the following command:

$ blueman convert api.json

Note: If you installed Blueman using Composer you have to replace blueman with ./bin/console in all the example commands, e.g.:

$ ./bin/console convert api.json

This command will generate a file called collection.json, which you can import in Postman.

By default Blueman will look for the JSON file in the same location as where you are running the command. If your file is in another directory, you need to specify the path:

$ blueman convert api.json --path=/Users/wouter/Desktop

Specify output file

By default Blueman will create a collection.json file in the current directory. You can save the file to a different folder and change the output filename by passing the output parameter:

$ blueman convert api.json --output=/Users/wouter/Desktop/postman_collection.json

Setting the host

The base host of your API can be set in a couple of different ways.

First of all you can specify it in your API Blueprint as metadata by adding the following line to the top of your API Blueprint Markdown file:

HOST: https://api.example.com/v1

If your Markdown file doesn't have the host metadata or if you want to overwrite it, you can specify the host when executing the convert command:

$ blueman convert api.json --host=https://api.example.com/v1

Lastly, if you don't do either of the above you'll be prompted to set the host when you execute the convert command.

TIP: If you use environments in Postman to test your API on different servers (sandbox, user acceptance testing, etc.) you can use the host option to specify your placeholder keys that you've setup in Postman's environment config:

$ blueman convert api.json --host=https://api.{{host}}/v1

Setting the Postman tests

You also may to define Postman's tests for your named Actions of Resources.

To use this feature do:

• create a Markdown formatted file in your path where api.json located (see --path option). By default, Blueman will be try get blueman.tests.md filename.
• read the markdown file example test/api.test.md
• write Postman tests for any Resource Action you want
• use --include-tests (default: unset) and --tests-filename (default: blueman.tests.md) options
• enjoy :)

Usage example

$ blueman convert api.json --include-tests 

or

$ blueman convert api.json --include-tests --tests-filename=<YOUR_FILNAME>.md