Using the JS Library

Adding the JS Library to your project

<script src="https://console.rest/github.io/libs/console-rest-api.js"></script>

Overall Architecture

This library is separated in 3 parts:

A web worker that does all the heavy lifting, such as as converting in between file formats, detecting formats, etc. This web worker is by default using the API-Flow library (https://github.com/luckymarmot/API-Flow) to do so.
A main-thread wrapper that interacts with the web worker in a relatively raw fashion.
A set of nice methods to interact easily with the wrapper, grouped in a simple library called ApiFlow.

Using ApiFlow

Simple Conversion Examples

From a URL

const converter = new ApiFlow()

converter.set({
  mode: 'url',
  url: 'https://api.apis.guru/v2/specs/instagram.com/1.0.0/swagger.json',
  name: 'Instagram API'
}).convert({
  target: {
    format: 'raml',
    version: 'v1.0'
  }
}).then(converted => {
  console.log('converted content', converted)
}, error => {
  console.error('failed to convert with error', error)
})

From a String

const converter = new ApiFlow()

converter.set({
  mode: 'text',
  text: 'curl -X GET https://xkcd.com/info.0.json',
  name: 'Current XKCD API'
}).convert({
  target: {
    format: 'swagger',
    version: 'v2.0'
  }
}).then(converted => {
  console.log('converted content', converted)
}, error => {
  console.error('failed to convert with error', error)
})

Simple Detection Examples

Detecting format

const converter = new ApiFlow()

converter.set({
  mode: 'url',
  url: 'https://api.apis.guru/v2/specs/instagram.com/1.0.0/swagger.json',
  name: 'Instagram API'
}).detect('format').then(format => {
  console.log('format of source is', format)
}, error => {
  console.error('failed to detect format with error', error)
})

Detecting name

const converter = new ApiFlow()

converter.set({
  mode: 'url',
  url: 'https://api.apis.guru/v2/specs/instagram.com/1.0.0/swagger.json',
  name: 'Instagram API'
}).detect('name').then(format => {
  console.log('suggested name for source is', name)
}, error => {
  console.error('failed to detect name with error', error)
})

Best Practices

A common usage pattern is to convert one source file in multiple formats. It is recommended to use converter.load to pre-fetch this, so that each conversion attempt does not reload the content.

const converter = new ApiFlow()
converter.set({
  mode: 'url',
  url: 'https://api.apis.guru/v2/specs/xkcd.com/1.0.0/swagger.json',
  source: {
    format: 'swagger',
    version: 'v2.0'
  }
})
.load() //loaded once asynchronously

const RAML1Promise = converter.convert({
  target: {
    format: 'raml',
    version: 'v1.0'
  }
}) // automatically use the pre-loaded content once it's ready

const Swagger3Promise = converter.convert({
  target: {
    format: 'raml',
    version: 'v3.0'
  }
}) // automatically use the pre-loaded content once it's ready

const OverridingPromise = converter.convert({
  mode: 'url',
  url: 'https://api.apis.guru/v2/specs/xkcd.com/1.0.0/swagger.json',
  target: {
    format: 'raml',
    version: 'v3.0'
  }
}) // does not use the pre-loaded content

API Description

Available Methods

set: a setter to update the internal settings of the converter.
load: a utility tool that tries to load content from raw text, urls or from a selector.
detect: a method to infer a few properties about a file.
convert: a method to convert a file from one format to another.
start: a method to start the web worker bound to this converter.
close: a method to stop the web worker bound to this converter.

`set`

Purpose

This setter updates the internal settings of the converter. These settings will be applied when using other methods such as detect or convert, unless overridden.

Arguments

converter.set has two possible arguments format:

converter.set(key, value)
converter.set(obj)

The set of key values that can be set using this method is:

{
  mode: 'url',
  url: 'https://api.apis.guru/v2/specs/instagram.com/1.0.0/swagger.json',
  text: null,
  selector: null,
  name: 'Instagram API',
  source: {
    format: 'swagger',
    version: 'v2.0'
  },
  target: {
    format: 'swagger',
    version: 'v3.0'
  }
}

Output

converter.set returns converter, so as to allow chaining.

`load`

Purpose

This method allows the converter to pre-load a resource that can then be used for conversions. It supports multiple resource locations such as a raw String (text), a remote resource (url) or a local DOM resource (selector).

Arguments

Obj (optional). An object that contains settings about where to find the resource. If no object is provided, the default settings will be used.

Output

converter.load returns an ES6 Promise. Once the content has been loaded successfully, it is also available at converter.content.

`detect`

Purpose

This method helps the converter infer informations about its source resource. It can infer both the format and name of the resource.

Arguments

action [required]. the property to detect. must be one of [ format, name ].
content (optional). A resource from which to infer the property. If no content is provided, the default content will be used. If no default content can be found, load() will be called.

Output

converter.detect returns en ES6 Promise. Once the property has successfully been inferred, it is also available at either converter.source or converter.name

`convert`

Purpose

This is the core method of ApiFlow and Console.REST. It transforms a resource from one file format to another.

Arguments

obj (optional) An object that contains settings about the resource, its format, and the target format. If no object is provided, the default settings will be used.

Output

converter.convert returns an ES6 Promise.

Advanced Usage

Custom worker wrapper

It is possible to use your own web worker wrapper, provided that it respects the expected behavior for such worker wrapper.

const workerWrapper = new MySpecialWorkerWrapper()
const converter = new ApiFlow(workerWrapper)

Custom ApiFlow Library

It is possible to use your own ApiFlow library, rather than the default one.

const converter = new ApiFlow()
converter.start('https://my-intranet-server/externals/api-flow.js')